johnbillion/wp-compat
A lightweight compatibility layer that lets you use WordPress functions and APIs outside of WordPress. Useful for plugins, libraries, and tools that need WordPress-style helpers without loading a full WordPress install.
Architecture fit. The first finding is a category mismatch worth surfacing before any engineering time is spent: johnbillion/wp-compat is not a Laravel package and has no Laravel integration surface. It is a PHPStan extension — a set of static-analysis rules that flag calls to WordPress APIs introduced after your declared minimum supported WordPress version. Its architectural fit is with codebases that ship WordPress plugins or themes. For a Laravel application, fit is effectively nil unless the product embeds WordPress (a headless WP backend, a Laravel app distributing a companion plugin, or a monorepo where a marketing site and plugin share tooling). If no such surface exists, this is a "no" on fit, not a "low-fit" — and the remaining sections should be read as conditional on that surface existing.
Integration feasibility. Where the fit is real, integration is cheap and well-bounded. It is a dev-only Composer dependency, configured via an includes: entry in phpstan.neon plus the declared minimum WordPress version and a matching set of WordPress stubs. It does not touch the application container, routing, service providers, or runtime. A PHP-fluent engineer familiar with PHPStan should have a working, scoped analysis job inside a day.
Technical risk. Three risks dominate, and two are metadata-level rather than technical:
unknown and the package carries 25 stars with a composite score of ~19.8. That is low signal for a quality gate you intend to trust in CI. Treat the package as untrusted until it is verified against Packagist and the upstream GitHub source, and pin by commit hash in the lockfile.Key questions. (1) Does any part of our codebase actually ship WordPress-targeting code? (2) If so, what is our declared minimum WordPress version, and who owns that policy? (3) Which PHPStan major version are we on, and does the extension declare support for it? (4) Is the extension's provenance verifiable against Packagist and a real upstream repository? (5) Should the resulting check be advisory or blocking? (6) Is there an internal owner willing to fork under MIT if upstream stalls?
Stack fit. A Laravel shop running Larastan already has PHPStan in place, which makes the tooling adjacent but the analysis not composable in the same run. WordPress stubs declare global functions and classes that collide with Laravel's global helpers and can either mask real errors or manufacture false ones. Do not add wp-compat to the existing Larastan config. Isolate it: a separate phpstan-wp.neon, a separate paths: scope limited to the WP-facing directory, and a separate CI job with its own cache key.
Migration path. (1) Confirm and document the WP-facing surface; if empty, stop here. (2) Ensure PHPStan is present and pinned to a version the extension supports. (3) Add WordPress stubs at exactly the declared minimum version — not latest. (4) Register wp-compat via includes:. (5) Generate a baseline so the first run is green and the gate is additive. (6) Wire CI as advisory, then promote to blocking once the false-positive rate is understood.
Compatibility. Three constraints to verify before committing: the extension's PHPStan version matrix, its PHP version floor versus our runtime, and Composer resolution against Larastan's own PHPStan constraint. A version conflict here is the most likely reason this work stalls midway, so resolve it in a spike before scheduling the rest.
Sequencing. Pin and vendor first, isolated config second, advisory CI third, blocking gate last. Do not add this to any shared tooling or template repository until a single team has run it for a full release cycle — the blast radius of a broken shared static-analysis config is every repository at once.
Maintenance. Low-velocity, likely single-maintainer, 25 stars. Budget for one or two interventions per year tied to PHPStan upgrades rather than to the extension's own roadmap. MIT licensing means forking or vendoring is a legitimate fallback and should be pre-approved as a contingency, not negotiated after a red build.
Support. No vendor, no SLA, GitHub issues only. Internal ownership is mandatory: a named team responsible for the CI job, the stubs version, and the minimum-WordPress-version declaration. Without that, the check silently rots.
Scaling. Runtime cost is zero — dev dependency only, nothing shipped. The scaling dimension is CI: analysis time grows with the scoped path, and triage effort grows with the WP-facing codebase. Both are manageable if the scope stays narrow. The failure mode to avoid is letting the WP stubs leak into the Laravel analysis path, where the cost is not performance but analysis correctness.
Failure modes. Ranked by severity: (1) silent no-op — the extension runs but the minimum version is unset or wrong, producing false confidence, which is worse than no check; (2) stubs/version mismatch producing false positives that train developers to ignore the gate; (3) PHPStan major upgrade breaking the extension and blocking unrelated work; (4) supply-chain exposure from an unverified unknown repository, mitigated by hash pinning and vendoring. Mitigate (1) with an explicit assertion in CI that the extension actually reports.
Ramp-up. PHPStan familiarity is likely already present; the genuine gap is WordPress domain knowledge — developers need to recognize version-gated APIs to act on findings. Expect half a day for the tooling setup and roughly a sprint of passive learning before the output is reliably actionable. Recommendation: pursue only if a WP-targeting surface exists, and treat the package metadata as unverified until provenance is confirmed.
How can I help you explore Laravel packages today?