Actions and filters

GOCSM exposes WordPress actions for observing completed operations and filters for changing policy or values. Register callbacks with add_action() or add_filter(), including the accepted argument count. Filters must return the filtered value on every path.

Register early enough for the event you need. A small custom plugin or MU plugin can observe PHP loading from the start of a request. A managed snippet can register callbacks for later events, but cannot observe its own earlier loading events.

Snippet and collection objects supplied to these hooks are snapshots. Changing an action argument does not save a change. Action callbacks should finish without throwing exceptions and should avoid recursively starting the same operation.

Snippet lifecycle #

Completed save events cover editor and Abilities API saves/patches (save), JSON import (import), Code Snippets migration (code_snippets_import), initial GitHub discovery (sync), automatic standalone adoption (collection_adoption), manual updates (manual_update), inline automatic updates (sync_update), cron updates (cron_update), and revision restoration (restore). $previous is null for creation. Skipped imports and unchanged sync entries do not emit save events. Imports can report configuration warnings; inspect their batch report when those details matter.

Additional status origins are activate, deactivate, run_once, execution, fatal, render, and status for other direct status writes. Deletion origins are delete and collection_delete. Direct low-level repository saves are persistence helpers and do not emit completed-operation save events.

gocsm_snippet_validation_errors filters an initially empty string[] $errors, with Snippet $proposed, SnippetConfig[] $configs, and string $origin. Return additional errors to refuse a save, activation, import, update, or restore. This does not replace built-in validation. The configuration array is empty for imports and initial GitHub discovery, which run this policy before parsing their configurations. Return an array of string messages; malformed returns also block the operation.

add_filter( 'gocsm_snippet_validation_errors', function ( $errors, $snippet, $configs, $origin ) {
    if ( 'activate' === $origin && str_contains( $snippet->name, '[draft]' ) ) {
        $errors[] = 'Remove the draft marker before activating this snippet.';
    }
    return $errors;
}, 10, 4 );

gocsm_snippet_adopted receives int $snippet_id, int $collection_id, and int $original_id (the Code Snippets ID, or zero). It fires after a successful collection handoff, source/config persistence, revision capture and generated-file cleanup. Adoption also emits the normal completed save event with origin collection_adoption; failed or ambiguous matches emit neither completed event.

PHP execution #

The before/success actions run outside the loader’s current-snippet attribution window. Integrity failures, missing files without eval fallback, and thrown exceptions never emit the success action or complete a run-once snippet. A success action reports successful top-level loading, not that every callback registered by the snippet will succeed later. Shutdown failure observers should do minimal work.

add_filter( 'gocsm_should_execute_snippet', function ( $execute, $snippet ) {
    if ( 'maintenance-task' === $snippet->manifest_id && wp_doing_ajax() ) {
        return false;
    }
    return $execute;
}, 10, 2 );

Configuration and generated files #

Config values are source-language expressions, not evaluated PHP values: return '42', not integer 42, for a numeric expression. Generated content must be a string. A non-string result fails generation. Keep generation/configuration filters deterministic: file-based snippets use the filtered content until regenerated, while eval prepares it on each execution. Re-activate or save active snippets after changing a generation filter.

GitHub synchronization and updates #

These hooks belong to tracked GitHub collections, which need the Premium or Agency plan. The plan is checked before any of them runs, so returning true from a filter cannot enable a feature the license does not include.

The auto-update origins are sync_update and cron_update; manual application uses manual_update. A successful collection result can include per-snippet fetch/reconciliation failures in its sync log. Completion reflects the collection result, not a promise that every member updated.

Rendering and assets #

Asset context is frontend, admin, or login. Asset filters run after context, page targeting, and file-existence checks. Return the argument array; omitted keys keep their defaults, while malformed values skip enqueueing. Handles remain gocsm-snippet-{id}. An invalid HTML output return produces an empty string. Escape any dynamic data inserted into HTML by your callback.

Import, export, revisions, and organization #

Export filters affect JSON; portable/runnable source-file exports retain their existing format. Configuration injection filters also apply when generating runnable exports.

Security scan #

Admin extension points and existing WordPress hooks #

gocsm_snippet_row_actions filters the action HTML array, keyed by action name, with a Snippet $snippet second argument. Escape added markup. Navigation links use target="_blank" rel="noopener noreferrer"; AJAX controls should be buttons. Register your own authorized handler for any added operation.

Four editor actions receive a Snippet $snippet: gocsm_before_snippet_editor (before the form), gocsm_snippet_editor_main (end of the main column), gocsm_snippet_editor_sidebar (before save controls), and gocsm_after_snippet_editor (after the form). Escape your output. Rendering fields does not automatically persist them; integrations own their request handling and permission/nonce checks.

The existing cron entry points are gocsm_check_collections, gocsm_apply_auto_updates, and gocsm_prune_sync_log. gocsm_fs_loaded fires when Freemius initializes. WordPress’s option filters/actions cover GOCSM settings (gocsm_default_auto_update, gocsm_sync_log_retention_days, gocsm_eval_fallback_mode, gocsm_opcache_invalidation_mode, gocsm_performance_tracking); its HTTP and cron hooks cover request customization and scheduling. Standard list-table column hooks remain available. Capability, API code-write, safe-mode, SSL, hash, and syntax checks retain their existing rules.