Wp Filter Side Effects Laravel Package

Getting Started

composer require alleyinteractive/wp-filter-side-effects

Then look in this order:

1. composer.json — v2.0.0 is a major bump, so check the require block first (PHP constraint, and whether the package now targets a narrower WordPress range). This is the fastest way to find the breaking change the changelog link is pointing at.
2. src/ — the package is intentionally tiny. You are looking for the invokable callable classes (FunctionCall and MethodCall) and how their __invoke() handles arguments and return values.
3. tests/ — the test suite is the real documentation for argument pass-through and return-value behavior; read it before wiring the callables into a production hook.

The first use case is replacing a throwaway closure with a named callable. Anywhere you have a filter that already fires and you only want a side effect (logging, cache busting, firing a notification), you can attach a function directly instead of writing function ( $value ) use ( ... ) { ...; return $value; }:

use Alley_Interactive\WP_Filter_Side_Effects\FunctionCall;

add_filter( 'myplugin_save_complete', new FunctionCall( 'myplugin_bust_cache' ), 10, 1 );

The payoff is legibility (the hook registration reads as "this hook calls this function") and testability (you can unit-test myplugin_bust_cache() without simulating the hook).

Implementation Patterns

Function calls for stateless side effects. Cache invalidation, logging, firing a webhook, incrementing a counter. Keep the wrapped function small and self-contained; the hook registration is then a one-line, greppable declaration of intent.

Method calls for service objects. When the side effect needs dependencies, instantiate the service once in your plugin bootstrap or service provider and register the method call:

add_filter( 'myplugin_save_complete', new MethodCall( $notifier, 'on_save' ), 10, 2 );

This is the pattern to prefer over use-capturing closures, because the object is explicit and you can swap it in tests.

Bulk registration in a bootstrap loop. Because the callables are objects, you can build a [ hook => callable ] map and loop over it in one place. This keeps hook wiring auditable in large plugins that register dozens of hooks.

Treating third-party filters as an event bus. Many plugins expose a filter purely as an extension point. Attaching a FunctionCall to it is a clean way to react to "something happened" without patching the other plugin. The same works for action hooks — actions are filters under the hood, and the return value is simply discarded.

Wiring across providers. Pass the callable into add_filter() from wherever you already have container access; don't let the package become a second registration mechanism. Keep add_filter/add_action as the single source of truth so remove_filter, Query Monitor, and $wp_filter inspection all keep working.

Gotchas and Tips

Verify the return contract before chaining. A filter callback must hand the filtered value back. If the wrapped callable's own return value (or null) is what comes out, you will silently break every downstream callback on that filter. Check tests/ for the pass-through behavior, then confirm with a two-callback filter where the second callback var_dumps its input.

accepted_args defaults to 1. If the hook passes three arguments, register with add_filter( $hook, $callable, 10, 3 ). A mismatch throws ArgumentCountError on PHP 8, which surfaces as a fatal mid-request rather than a warning.

Object identity matters for removal. remove_filter() and has_filter( $hook, $callable ) compare by identity for objects. Store the instance (property, container singleton) if you ever need to unhook it; a freshly constructed new MethodCall( $obj, 'method' ) will not match.

Watch object lifetime. The hook array holds a reference to your callable for the whole request, and transitively to whatever service it wraps. Registering a MethodCall around a heavy service at plugins_loaded keeps that service (and its dependencies) alive for every request, including ones that never hit the hook. Prefer lazy resolution or register later, on the hook that actually needs it.

Serialization and cloning. These callables survive serialization better than closures, which makes them tempting to stash in options or the object cache — don't. The wrapped object graph will be serialized with them and will break on the next deploy.

Debugging. Dump $GLOBALS['wp_filter'][ $hook ] or use Query Monitor's Hooks panel; the callable shows as a class name plus method, which is more readable than a closure. If a side effect isn't firing, check priority and whether an earlier callback on the same filter returned early.

Extension point. You rarely need to subclass. If you need custom argument shaping, write your own __invoke( ...$args ) class and register it — the hook system only cares that it is callable.

Upgrading from 1.x. The v2.0.0 release notes are a bare changelog link, so treat this as an unknown-breakage major: diff composer.json (PHP floor), confirm the namespace and class names in src/ still match your use statements, and re-run any tests that assert on hook registration before deploying. If you pin the package on client sites, do the bump in a branch and smoke-test the specific hooks you registered.