Wp Filter Side Effects Laravel Package

Technical Evaluation

Architecture fit The release under review is alleyinteractive/wp-filter-side-effects v2.0.0 — a WordPress-side library, not a Laravel package. It exists to attach side effects to WordPress filter hooks (add_filter / apply_filters) so that callbacks which mutate state, dispatch jobs, or perform I/O can be registered against a filter without violating the "filters should be pure" convention. Architecturally this only fits our stack if the target application embeds WordPress (Roots/Sage, Bedrock, a headless WP content service, or a Laravel app fronting a WP install via Corcel/DB). In a conventional Laravel application — service container, middleware pipeline, event/listener system — the package has no natural seam: Laravel already provides Event/Listener, Job dispatch, and model observers, all of which are the idiomatic equivalents of what this library offers.

Integration feasibility Composer-installable and PSR-4 autoloaded, so pulling it in is trivial. Runtime is the constraint: the library expects WordPress hook functions (add_filter, apply_filters, did_filter, current_filter) to exist globally. In a Laravel-only runtime these are undefined and every entry point fatals unless we ship a shim, which defeats the purpose. In a hybrid runtime (WP loaded alongside Laravel, or a WP-first app with Laravel components), integration is genuinely low-effort — register the side effects during theme/plugin bootstrap.

Technical risk

• Major version bump with unreadable detail. v2.0.0 is by definition a breaking release, and the release body contains no content beyond a link to the upstream changelog. The changelog was not retrievable in this review cycle, so we are being asked to accept a semver-major change with zero visibility into the break surface. That is the single largest risk here and should block adoption until the diff is read.
• Likely breaking surface for a library of this shape: minimum PHP version, minimum WordPress version, changed function/class signatures or namespacing, altered execution/ordering semantics for registered side effects, and possible removal of deprecated helpers. Any of these can silently change when and how often a side effect fires.
• Maintainership. Agency-maintained (Alley Interactive), narrow-scope utility, low traffic. Bus factor is low; expect slow responses on issues and infrequent releases.
• Blast radius. Side effects tied to filters are, by design, implicit control flow. A regression here does not throw — it double-charges a card, double-sends an email, or drops an event.

Key questions

1. What exactly is in the v2.0.0 changelog — is the break a PHP/WP floor bump, a namespace change, or a semantic change to side-effect execution (at-most-once guarantees, priority handling)?
2. Which runtime are we actually targeting: pure Laravel, pure WordPress, or hybrid? If pure Laravel, why are we evaluating this at all?
3. Is there an existing v1.x dependency anywhere in our portfolio, and what is the upgrade cost?
4. Does v2.0.0 change how side effects are deduplicated or ordered relative to did_action/did_filter?
5. What is the maintainer's stated support window and PHP/WP compatibility matrix for the 2.x line?
6. Is there a maintained fork or first-party alternative if we need to fork?

Assessment confidence: low. Based on the release metadata only; the upstream changelog was not available at review time.

Integration Approach

Stack fit Conditional. Green-light only for WordPress-adjacent services — a headless WP content API consumed by a Laravel frontend, or a Laravel app that boots WordPress in-process. Red-light for standard Laravel services: use Event/Listener, queued jobs, or model observers instead. Adopting this library in a pure Laravel codebase would introduce a WordPress runtime dependency for functionality Laravel already provides natively.

Migration path Do not upgrade blind. Sequence: (1) pin current v1.x and capture the resolved version; (2) read the full changelog and the v1→v2 diff on GitHub; (3) branch-upgrade in a staging environment with WordPress debug logging on; (4) diff behavior by asserting side-effect invocation counts before and after for every registered filter; (5) only then promote. If the changelog reveals a semantic change to when side effects fire, treat it as a functional change requiring QA sign-off, not a routine dependency bump.

Compatibility Confirm three floors before merging: PHP version against our runtime images, minimum WordPress version against our fleet (including any legacy sites), and Composer constraint conflicts with existing WP plugin dependencies. Check whether v2.0.0 drops support for a WP version we still operate. Also verify the library remains compatible with our hook-documentation and static-analysis tooling, since implicit side-effect registration is invisible to linters.

Sequencing Low urgency unless a v1.x security or correctness issue forces the move. Recommended order: read changelog → pin and freeze v1.x → inventory every call site → stage upgrade → behavioral verification → production. Do not bundle this with unrelated dependency upgrades; if a side effect misfires, we want a single-variable diff. If the changelog turns out to be a documentation/metadata-only bump, fast-track it.

Operational Impact

Maintenance Low ongoing surface — small, focused library. The real maintenance cost is the implicit coupling it creates: side effects live at a distance from the code that triggers them, so future engineers must know the filter contract to reason about behavior. Budget for inline documentation at every registration site. Track upstream releases; the 2.x line will likely see patch churn in the weeks after a major.

Support Agency-maintained, community-supported, no commercial SLA. Escalation path is GitHub issues and, ultimately, forking. Given the small codebase, forking is a viable fallback — but that converts an external dependency into an owned one, which needs explicit owner assignment before it happens.

Scaling Runtime overhead is negligible; the concern is behavioral scaling. As filter registrations grow, side-effect ordering and at-most-once guarantees become harder to verify, and issues surface only under specific request paths. In multi-tenant or high-concurrency setups, pay attention to anything that assumes a single execution per request — caching layers and full-page caches can short-circuit filters so side effects never fire, while retries can fire them twice. Ensure side effects are idempotent wherever possible.

Failure modes

• Silent no-op: the filter is never applied (cached page, short-circuited hook, early return) — the side effect simply never runs, with no error.
• Double execution: filter applied more than once per request, or the request is retried — duplicate emails, duplicate charges, duplicate webhooks.
• Ordering regressions: a v2.0.0 change to priority or dedup semantics reorders effects in ways tests do not catch unless invocation counts are asserted.
• Hard fatal: WP hook functions absent in a non-WP runtime — immediate Error on bootstrap, at least loud and easy to catch.
• Version skew: mixed v1/v2 across services in a shared WordPress install (plugin conflicts) producing inconsistent side-effect behavior.

Ramp-up Low for anyone with WordPress filter experience — the concept is one sentence ("run this when that filter is applied"). Higher for Laravel-native engineers with no WP background, who will reach for events and jobs first and may misread the library as redundant. Recommend a short internal note covering the WP filter contract, why side effects are separated from filter return values, and the invocation-count testing pattern before this enters the codebase.