This skill is about hooks the plugin emits as its public extension surface — the actions and filters other developers wire into to modify or react to the plugin's behavior. Using core WP hooks (init, wp_enqueue_scripts, the_content, etc.) is basic WP and out of scope; designing your own hooks well is what separates a plugin people can extend from one they have to fork.
A custom hook is part of your plugin's API contract. Once a third party builds on it, breaking the signature in a minor release is a backwards-incompatibility bug — same as renaming a public PHP method.
\nTrigger when ANY of the following is true:
\ndo_action or apply_filters call that other plugins / themes will hook into.do_action, apply_filters, apply_filters_deprecated, do_action_deprecated, or a docblock starting with Fires / Filters above a hook call.Both are events your code emits during execution. The semantic difference:
\n| Hook type | \nQuestion it answers | \nWhat listeners do | \nReturn | \n
|---|---|---|---|
Action (do_action) | \n\"This thing happened — anyone want to react?\" | \nSide effects (log, send email, update meta, schedule cron). Don't return a value. | \nNone | \n
Filter (apply_filters) | \n\"I have this value. Anyone want to modify it before I use it?\" | \nTake the value, optionally transform it, return it. | \nThe (possibly modified) value | \n
Concrete examples:
\n// ACTION — \"the user just submitted the form\"; downstream side effects\ndo_action( 'myplugin/form_submitted', $form_id, $submission );\n// Listeners: send Slack notification, log to audit table, dispatch webhook.\n\n// FILTER — \"here's the response message; anyone want to override?\"\n$message = apply_filters( 'myplugin/response_message', $default_message, $form_id );\n// Listeners: replace the message based on form_id, append \"(internal)\" prefix.\nIf listeners might want to MUTATE the data flow, it's a filter. If they want to REACT to an event, it's an action. When in doubt: would removing all listeners change the plugin's output? Yes → filter. No → action.
\nWP core mostly uses underscore_style names (pre_get_posts, rest_pre_serve_request). Slash-style names are common in plugin ecosystems for namespaced surfaces (myplugin/before_request), but they are not the dominant core convention. The hard rule: prefix with the plugin slug so collisions are impossible.
// Slash-separated - visually clear that this is plugin-namespaced\ndo_action( 'myplugin/before_request', $payload );\napply_filters( 'myplugin/api_response', $response, $request );\n\n// Underscore-separated - matches WP core convention\ndo_action( 'myplugin_before_request', $payload );\napply_filters( 'myplugin_api_response', $response, $request );\nPick one style and stay consistent across the plugin. Mixing myplugin/before_request and myplugin_after_request in the same plugin is confusing for documentation tools and developers searching the source.
The @since + @param block above each hook call is non-negotiable — IDE tooltips, source-search tools (hooks.wp.org, AI assistants suggesting hooks), and humans grepping for hooks all depend on it.
/**\n * Fires before the AI request is sent.\n *\n * @since 1.2.0\n *\n * @param array $payload The request payload.\n * @param string $context Reason for the request: 'verdict' or 'enrichment'.\n */\ndo_action( 'myplugin/before_request', $payload, $context );\n\n/**\n * Filters the AI response message that will be shown to the user.\n *\n * @since 1.0.0\n * @since 1.3.0 Added the `$decision` parameter.\n *\n * @param string $message The response message.\n * @param int $form_id ID of the form being processed.\n * @param bool $decision The AI's TRUE/FALSE verdict.\n *\n * @return string Possibly modified message.\n */\n$message = apply_filters( 'myplugin/response_message', $message, $form_id, $decision );\nConventions:
\nFires for actions, Filters for filters as the opening verb in the description (matches WP core docblocks; documentation generators grep for it).@since X.Y.Z for the version when the hook first appeared, plus a separate @since line for each later parameter addition.@return describes the return type — same shape as the input value (filters MUST preserve type).Three rules govern parameters that age well:
\nFor filters, the first arg is always the value being filtered. For actions and filters alike, arrange other args in order of likely use — listeners often only want one or two pieces of context. If the form ID is the most useful piece for filtering, put it second.
\n// Better — form_id is more often useful than the full submission array\napply_filters( 'myplugin/should_process', true, $form_id, $submission );\n\n// Worse — listener has to accept submission they don't need to skip past\napply_filters( 'myplugin/should_process', true, $submission, $form_id );\nListeners may only need the form ID; passing the whole Form object means every listener carries the full object even if they ignore it. When the work to fetch the object is cheap (small DB hit), pass the ID; when listeners always need the object anyway, pass it.
Beyond 4 args, listeners get unwieldy. If you find yourself wanting 5+ args, bundle them into an associative array:
\n// 6-arg action — listeners must accept all six in order\ndo_action( 'myplugin/render', $template, $context, $vars, $depth, $strict, $cache_key );\n\n// Better — single context array, listeners pick what they need\ndo_action( 'myplugin/render', array(\n 'template' => $template,\n 'context' => $context,\n 'vars' => $vars,\n 'depth' => $depth,\n 'strict' => $strict,\n 'cache_key' => $cache_key,\n) );\nThe trade-off: array-as-arg loses static analysis benefits. For 2-3 strongly-typed args, prefer separate parameters; for 5+ heterogeneous fields, bundle.
\ndo_action_ref_array / apply_filters_ref_array — when args are dynamicThe standard do_action( $hook, ...$args ) and apply_filters( $hook, $value, ...$args ) use variadic spread (PHP 5.6+). When you DON'T know the args at compile time — typically when proxying / forwarding hook calls — use the array variants:
$args = array( $payload, $context, $extra );\n\n// Spread variant — only when args are statically known\ndo_action( 'myplugin/event', $payload, $context, $extra );\n\n// Array variant — args are an array dynamically\ndo_action_ref_array( 'myplugin/event', $args );\nThe naming _ref_array is historical. These functions accept the hook arguments as an array and pass that array to WP_Hook; they are primarily \"args-as-array\" variants. References only matter if the array elements themselves are references, so do not reach for these functions as a generic \"make callback args mutable\" tool. Verified in wp-includes/plugin.php apply_filters_ref_array / do_action_ref_array.
99% of plugin code uses the spread variants. Reach for the array variants only when forwarding (apply_filters_deprecated uses them internally for exactly this reason).
Once a hook is documented and shipped:
\n@since annotation; reordering or removing is a major version bump.int $form_id to string $form_slug is a breaking change.string shouldn't suddenly return string|null.Track public hooks in your plugin's documentation / README under a \"Hooks\" section. Treat them with the same rigor as the public methods of a class.
\nWhen you genuinely must change or remove a hook, deprecate, don't delete. WordPress provides apply_filters_deprecated and do_action_deprecated (wp-includes/plugin.php, since WP 4.6) that fire the hook for any remaining listeners AND emit a _deprecated_hook notice (wp-includes/functions.php).
// OLD HOOK (now deprecated): myplugin/old_response\n// NEW HOOK: myplugin/response_message\n\n// Step 1: emit BOTH hooks so existing listeners keep working.\n$message = apply_filters( 'myplugin/response_message', $default, $form_id );\n\n// Fire the deprecated hook with the same args; emits _deprecated_hook notice.\n$message = apply_filters_deprecated(\n 'myplugin/old_response', // old hook name\n array( $message, $form_id ), // args (as array)\n '1.5.0', // version when deprecated\n 'myplugin/response_message', // replacement\n 'Use myplugin/response_message instead.' // optional message\n);\nFor actions:
\ndo_action_deprecated(\n 'myplugin/old_event',\n array( $payload ),\n '1.5.0',\n 'myplugin/new_event'\n);\nThe deprecation helpers short-circuit when no listener is attached (has_filter / has_action returns false), so they're cheap when nobody's listening. The notice fires only when someone IS still using the old hook — exactly when you want them informed.
Deprecation policy: keep the deprecated hook for at least one major version. 1.5.0 deprecates → 2.0.0 removes. Document the migration in the changelog.
slash/style or underscore_style, stay consistent.Fires / Filters opening, @since, every @param typed and described, @return for filters.string returns string (or you've designed it badly). Listeners who break the type get to fix their callbacks; you don't change the contract on them.apply_filters_deprecated / do_action_deprecated, never silent-delete a public hook.// WRONG — action used as a filter (return value lost)\n$result = do_action( 'myplugin/transform', $value ); // do_action returns void\n\n// WRONG — filter that doesn't return the value\nadd_filter( 'myplugin/response_message', function ( $message ) {\n error_log( $message ); // side effect\n // missing: return $message;\n} );\n// Other listeners receive the previous value or null; chain breaks.\n\n// WRONG — bare hook name, collides with the world\ndo_action( 'before_save', $data );\n\n// WRONG — adding a parameter in the middle, breaking existing listeners\n// v1.0\napply_filters( 'myplugin/response_message', $msg, $form_id );\n// v1.1\napply_filters( 'myplugin/response_message', $msg, $context, $form_id ); // BUG — breaks existing listeners\n\n// RIGHT — append at the end, document with @since\napply_filters( 'myplugin/response_message', $msg, $form_id, $context );\n\n// WRONG — silent removal\n// (the hook just stops firing, listeners get no warning)\n\n// RIGHT — deprecate first\n$message = apply_filters_deprecated(\n 'myplugin/old_response',\n array( $message, $form_id ),\n '1.5.0',\n 'myplugin/response_message'\n);\n\n// WRONG — undocumented hook\ndo_action( 'myplugin/before_request', $payload );\n// IDE / hooks search tools / AI assistants can't find or describe this hook.\nwp-plugin-architecture — the hook-naming convention is part of broader plugin architecture. Schema/Constants centralization includes hook names for discoverability.wp-i18n-audit if any of your hooks pass translatable strings as args — translation timing rules apply to the values, not the hook names.wp-security-audit when your hook callback receives user input that downstream listeners will trust — document the sanitization expectation in the @param line.init, the_content, save_post, etc.) — every WP plugin does this; not a custom-hook design topic.add_action( $hook, $cb, $priority )) — basic WP, not a design topic for the plugin emitter.remove_filter / remove_action — adjacent topic, separate skill.wp-plugin-architecture).'all' meta-hook (a debugging tool, not a design pattern).apply_filters / do_action: wp-includes/plugin.phpapply_filters_deprecated / do_action_deprecated: wp-includes/plugin.php (since WP 4.6)_deprecated_hook (the underlying notice trigger): wp-includes/functions.phpdid_action / did_filter: wp-includes/plugin.php — useful in tests / debugging to assert a hook fired.