Pro module11 abilities

Code Snippets ability reference

Reference for the GoBuildWP Pro 1.12.4 source. Installed schemas and policy remain authoritative.

The Code Snippets module lets an agent list, read, write, lint, switch on and off, and delete snippets in the Code Snippets plugin, free or Pro. This Code Snippets ability reference covers how a snippet moves from saved to running, and the checks GoBuildWP places between the two.

By GoBuildWPContent updated 10 October 2026How we check claims

Read-only, write and destructive groups describe the source annotations. They do not establish a minimum safety profile, human approval or undo support. Those controls are separate: check the installed ability, the connected user and the active site policy before calling it. A read can still return sensitive data. These pages are not evidence that every operation passed an end-to-end runtime test.

What Code Snippets needs before these load

Code Snippets 3.6.0 or newer; the gate checks CODE_SNIPPETS_VERSION and the Code_Snippets\code_snippets() function. The free plugin offers php and html snippets; Code Snippets Pro, recognised by its code-snippets-pro plugin folder, adds css, js and cond, and does not need its licence activated for these calls. Calls need manage_options. Every write belongs to a critical risk category, so it is withheld under Production Safe and runs under Developer Full Access with confirmation; the reads stay available.

Minimum (base): 3.6.0 WPPILOT_PRO_CODE_SNIPPETS_MIN_VERSION
Code Snippets editions: free, pro
Agent skills shipped: code-snippets-integration

From saved to running

A new snippet is saved inactive. Saving it active needs activate=true and confirm=true, and code-snippets-enable-snippet asks for confirm on every call, even for a snippet already on, answering wppilot_confirmation_required (HTTP 409) with the snippet's id, type and scope. On an active snippet, an edit to code, type, scope or condition_id needs confirmation too; name, description, tags and priority do not.

code-snippets-validate-snippet parses PHP without executing it and returns the failing line with the lines around it; other types are skipped. It cannot catch an undefined function. Code Snippets test-runs an active PHP snippet when it is saved and switches it off if that fails, which the edit result reports as deactivated_on_save with the code_error.

Limits the plugin does not report clearly

Names over 255 bytes fail with cs_name_too_long, code that is not valid UTF-8 with cs_invalid_utf8, and a tag containing a comma with cs_invalid_tag, because tags are stored as one comma-separated string. Type and scope must match (a php snippet takes global, admin, front-end or single-use). A css, js or cond snippet on a free install, including one left behind after Pro was deactivated, returns cs_pro_required.

No undo, delete included

Snippets live in the plugin's own table, so the change ledger records every write as irreversible. Delete is permanent; the plugin deactivates the snippet before removing it, but cron events, tables or options the code created stay behind, so disable it and clean those up before deleting.

Representative call sequence

This sequence describes the documented calls and checks to perform. It is not a recorded result from an installed WordPress site. Inspect returned errors and partial results, then verify the saved values and affected output before proceeding.

Add a PHP filter for the front end and switch it on once reviewed.

01 wppilot/code-snippets-get-types-schema Called with type php, returning the valid scopes and when each one runs.
02 wppilot/code-snippets-create-snippet Saves the code inactive and returns its id.
03 wppilot/code-snippets-validate-snippet Parses the stored code by id and returns valid, or the failing line with context.
04 wppilot/code-snippets-enable-snippet Activates it with confirm=true after the user has seen the code.

Questions about Code Snippets

Why does enable-snippet ask for confirmation when the snippet is already active?

On purpose. The confirmation check comes before the already-active shortcut, so whether the agent must ask never depends on the snippet's current state, and an agent does not learn to skip it.

How do I get an old version of a snippet back after an edit?

The ledger cannot restore it. Read the snippet with code-snippets-get-snippet before editing and keep its code, then edit it back if needed.

Code Snippets reads

Ability	What it does
`wppilot/code-snippets-check-setup`Check Code Snippets Setup	Returns a snapshot of the Code Snippets install: which variant is active (free or Pro), version, whether the minimum supported release is satisfied, the list of snippet types available on this install (free = php/html; Pro adds css/js/cond), and counts of total / active snippets. Call this once at the start of any session that will read or write snippets.
`wppilot/code-snippets-get-conditions-schema`Get Conditions Schema	Pro-only reference for the Code Snippets conditions feature. A condition is itself a snippet of type=cond + scope=condition whose `code` field stores a JSON tree of rules; other snippets attach to a condition via their `condition_id`. This ability returns the catalog of supported subjects (siteArea, currentQuery, postType, userRole, currentDate, …), their operators (`equals` is implicit; date subjects also support `before` / `after` / `between`), and a worked JSON example so an agent can compose valid conditions without reading the plugin source. Returns `available: false` on a free install since conditions are Pro-only.
`wppilot/code-snippets-get-snippet`Get Code Snippet	Reads a single snippet by id, including the executable `code` body and all metadata (name, desc, type, scope, tags, priority, active flag, modified timestamp, revision, condition_id, plus a `shortcode` field when type=html scope=content). Returns WP_Error `cs_not_found` when the id does not exist.
`wppilot/code-snippets-get-types-schema`Get Code Snippets Types Schema	Returns the type / scope reference for Code Snippets: which type accepts which scope values, what each scope means in terms of when the snippet runs, and which types require Code Snippets Pro. Pass `type` (e.g. "php") to receive only that type entry - useful when an agent already knows the family and wants to keep the response small. Otherwise the full matrix is returned. Call this once before authoring a snippet so create / edit send the right type+scope pair on the first try.
`wppilot/code-snippets-list-snippets`List Code Snippets	Lists snippets with optional filters. Response is a compact summary per snippet - id, name, type, scope, tags, priority, active, network, modified - WITHOUT the `code` field so listings stay small. Call code-snippets-get-snippet with a specific id to read the executable code. Filters: `type` (php\|html\|css\|js\|cond), `scope`, `active` (bool), `tag` (substring match against the snippet's tag list), `search` (case-insensitive substring match against name, desc, and code). Pagination: `limit` (default 100, max 500 - values above the cap are REJECTED with ability_invalid_input, not silently clamped), `offset` (default 0, must be ≥0). `total` in the response always reflects the unpaginated match count so the agent knows whether to keep paging.
`wppilot/code-snippets-validate-snippet`Validate Code Snippet	Lints a PHP snippet body for syntax errors WITHOUT saving or executing it. The check runs `token_get_all($source, TOKEN_PARSE)` over the prefixed source so PHP's parser walks every token (catching both ParseError and CompileError, which is what some PHP 8.4 constructs throw) but never invokes the runtime. Use this as a pre-flight step before code-snippets-enable-snippet. For non-PHP types (html / css / js / cond) the call returns `valid: true, skipped: true` immediately - `cond` bodies are JSON, not PHP, so running the parser on them would produce false negatives. To lint a snippet you have NOT saved yet, pass `code` directly; to lint an existing snippet, pass `id`.

Code Snippets writes

Ability	What it does
`wppilot/code-snippets-disable-snippet`Disable Code Snippet	Deactivates a snippet by id. The snippet body stays in the database (unchanged) but stops executing on the next request. Reversible by code-snippets-enable-snippet. Calling disable on an already-inactive snippet is a no-op.

Destructive Code Snippets calls

Ability	What it does
`wppilot/code-snippets-create-snippet`Create Code Snippet	Creates a new snippet. Required: `name`, `code`, `type` (php\|html\|css\|js\|cond), `scope`. Optional: `desc`, `tags[]`, `priority`. SAFETY: the new snippet is always created INACTIVE - it is saved to the database but does NOT run on the site until you call code-snippets-enable-snippet (or pass `activate: true` to opt into immediate activation, in which case the agent takes responsibility for the safety review). The css / js / cond types require Code Snippets Pro on this install; the response surfaces a clear error when an unavailable type is requested. Note: Code Snippets does NOT enforce unique `name` - multiple snippets may share the same name; identify rows by the id returned in `snippet.id`. Note: operates on the per-site `wp_snippets` table only; network-shared snippets in `wp_ms_snippets` are out of scope.
`wppilot/code-snippets-delete-snippet`Delete Code Snippet	Permanently removes a snippet by id. There is no soft-delete - once deleted the snippet cannot be recovered via the abilities. The plugin auto-deactivates active snippets before delete so the code stops executing immediately. IMPORTANT: delete only removes the snippet row - it does NOT undo durable side effects the snippet body created during prior executions (scheduled WP-Cron events via wp_schedule_event survive the delete and continue firing forever as silent no-ops; dbDelta-created tables remain; persisted options remain). For snippets that wired durable side effects, prefer code-snippets-disable-snippet first, then have the user run a cleanup snippet to reverse those effects, then delete.
`wppilot/code-snippets-edit-snippet`Edit Code Snippet	Merges new field values into an existing snippet identified by id. Only the keys you pass are changed - omitted keys keep their current value. To change `type` and `scope` together, pass both (changing one without the other often produces an invalid pair). The active flag is NOT touched here - use code-snippets-enable-snippet / code-snippets-disable-snippet for toggling execution. Code Snippets re-validates the PHP code on save and deactivates the snippet if the code errors; the result then includes deactivated_on_save and code_error.
`wppilot/code-snippets-enable-snippet`Enable Code Snippet	Activates a snippet by id. From this point on, the snippet code runs on every matching request (based on its scope) - for PHP that means it can hook into actions / filters, for HTML it becomes a shortcode or head/footer markup, for CSS / JS it gets enqueued. ALWAYS call code-snippets-validate-snippet first on PHP bodies - the plugin only catches a narrow set of activation-time problems (duplicate function names, missing class identifiers) and surfaces those under `error_line`; a plain PHP syntax error slips past activation and fatals on the next render. Calling enable on an already-active snippet is a safe no-op (returns `success: true` without re-firing activation hooks).

For the task-level view of Code Snippets, with worked requests and what to check afterwards, see Code Snippets integration page.