View Categories

Creating Your Own Snippet Library

0:00 3:08
Table of Contents

This guide is for developers who want to publish a snippet library that can be imported by any GOCSM user.

Repository structure #

Recommended layout:

my-snippet-library/
├── snippets.json
├── redirect-login.php
├── disable-admin-bar.php
└── custom-js-helper.js

One file per snippet. Any directory structure works as long as file paths in snippets.json are correct.

The snippets.json manifest #

{
  "manifest_version": "1.0",
  "collection": {
    "name": "My Snippet Library",
    "slug": "my-snippet-library",
    "version": "1.2.0",
    "description": "A curated set of useful snippets."
  },
  "snippets": [
    {
      "id": "redirect-login",
      "name": "Redirect after login",
      "description": "Redirects subscribers to the homepage after login.",
      "type": "php",
      "file": "redirect-login.php",
      "hash": "sha256:<64-hex-character-hash>",
      "version": "1.0.0",
      "tags": ["login", "users"],
      "scope": {
        "context": "everywhere",
        "hook": "init",
        "priority": 10
      },
      "requires": {
        "php": "8.0",
        "wordpress": "6.0",
        "plugins": []
      }
    }
  ]
}

Required manifest fields #

Field Description
manifest_version Must be 1, "1", or "1.0".
collection.name Display name shown in GOCSM.
collection.slug Lowercase alphanumeric and hyphens only. Validated and stored as metadata; GOCSM’s own collection slug and filenames come from the display name or user/repo.
collection.version Version string shown in the collection table. Increment when any snippet changes.
snippets[].id Stable unique ID. Lowercase alphanumeric and hyphens only, and unique within the manifest. Never change this after publishing.
snippets[].name Display name.
snippets[].type "php", "js", "css", or "html".
snippets[].file Path to the file, relative to snippets.json. Must not start with /, contain . or .. segments or empty segments, or be a URL.
snippets[].version Version string for this snippet.
snippets[].hash Hash of the file contents in sha256:<64 hex chars> format.

Optional manifest fields #

Field Description
collection.description and other collection keys Stored as collection metadata.
snippets[].description Description shown on the snippet.
snippets[].tags Array of tag names to assign to the snippet.
snippets[].scope Default scope settings, applied when the snippet is first imported. Keys match the Scope card: context, hook, priority, run_once (PHP); targeting, urls, pattern, post_types, templates, dependencies, version (JS and CSS); location, strategy (JS); media (CSS); location, priority, and the targeting keys (HTML).
snippets[].requires Environment requirements checked at activation. Supports php, wordpress, and plugins — an array of plugin basenames such as gravityforms/gravityforms.php.
snippets[].changelog_url Link shown in the update reconciliation modal.

Generating hashes #

# Linux
sha256sum redirect-login.php
# Manifest value: sha256:<hash-from-output>

# macOS
shasum -a 256 redirect-login.php
# Manifest value: sha256:<hash-from-output>

Writing config blocks #

If your snippet has site-specific values (form IDs, URLs, messages), declare them in a config block so users can customize without editing the code. See Config Block Syntax — PHP.

Versioning strategy #

  • Increment snippets[].version whenever a snippet file changes.
  • Increment collection.version whenever any snippet changes. GOCSM stores this for display and collection metadata; per-snippet version and hash determine whether a snippet changed.
  • Keep snippets[].id stable across file renames — GOCSM matches snippets by ID, not by filename.
What are your Feelings