Phpstan Wordpress Laravel Package

Product Decisions This Supports

• Quality-gate investment (build vs. buy): Adding static analysis to WordPress plugin/theme codebases is normally a multi-sprint effort (stub generation, type extensions for apply_filters(), WP_Error narrowing, dynamic constants). This package collapses that into a dev dependency — the decision becomes "do we enforce static analysis at all?" rather than "can we afford to build WordPress-aware analysis?"
• CI/CD roadmap item: Enables a concrete, low-cost engineering initiative — PHPStan at level 5+ in the pipeline, blocking merges on new type errors. Directly improves defect escape rate without new headcount.
• PHP and WordPress upgrade readiness: Because the extension ships stubs for core functions, constants, and hook signatures, it makes PHP 8.x / WordPress major-version upgrades auditable before rollout. Useful input to "when do we schedule the platform upgrade?" decisions.
• Refactor and modernization planning: Accurate return types for get_sites(), term_exists(), wp_parse_url(), has_filter(), is_wp_error(), and hook callback signatures give teams the confidence to restructure legacy plugin code — a prerequisite for any "clean up the monolith plugin" roadmap item.
• Filter/hook contract discipline: The apply_filters() docblock validation turns informal, undocumented hook contracts into machine-checked ones. This supports decisions about extensibility standards and public API stability for plugins that ship hooks to third parties.
• Portfolio triage (agencies, multi-plugin owners): Cheap to apply uniformly across many legacy plugins; static-analysis error counts become a defensible prioritization metric for remediation backlogs.
• WooCommerce-adjacent work: Pairs with php-stubs/woocommerce-stubs for e-commerce plugin and theme estates.

When to Consider This Package

Adopt when:

• You maintain one or more WordPress plugins/themes in-house and have (or want) PHPStan in CI.
• You are on PHPStan 2.0+ and PHP 7.4–8.4; the package is a no-config drop-in (extension.neon or phpstan/extension-installer).
• You want filter/hook return types inferred rather than annotated by hand, or you need core constants and stubs resolved without maintaining your own bootstrap.
• You are preparing a PHP or WordPress version upgrade and need a fast, repeatable compatibility signal.
• A small team needs an off-the-shelf baseline before investing in deeper, custom rules.

Look elsewhere or defer when:

• Maintainer continuity is a hard requirement. The README carries an explicit notice that the maintainer plans to stop contributing to the WordPress ecosystem and is seeking sponsorship. Single-maintainer bus factor is the dominant risk — treat this as a dependency to be vendored/pinned and monitored, not assumed durable.
• You need commercial SLAs, guaranteed CVE response, or vendor support.
• You are on PHPStan 1.x — requires the older 1.x line of this package; plan the PHPStan 2 migration together.
• You need analysis of code that isn't reachable without a runtime environment (this is static stubs, not behavioral testing).
• You need deep custom domain rules — you'll be authoring your own PHPStan rules regardless; this package is the substrate, not the whole answer.
• Teams with no static-analysis maturity: adopting it without a baseline level and suppression policy produces noise, not value.

Mitigations to require before adoption: pin an exact version, commit the lockfile, record the fallback (php-stubs/wordpress-stubs plus a hand-rolled extension.neon), and have one engineer able to fork it.

How to Pitch It (Stakeholders)

For executives: We can add automated correctness checking to our WordPress code for effectively zero license cost — it's MIT-licensed, installs as a dev dependency, and requires no configuration. It catches type errors, bad hook contracts, and upgrade incompatibilities at code-review time rather than in production. The decision is approval of a CI policy change, not a procurement. Principal caveat: it is maintained by a single volunteer who has publicly signaled intent to step back, so we should pin the version, own the fallback, and not treat it as a long-term vendor commitment.

For engineering leadership: This is the standard way to make PHPStan understand WordPress — core stubs, dynamic return types for functions the stubs miss, core constants, and apply_filters()/do_action() docblock validation. No setup beyond including extension.neon. It also enforces better habits: precise PHPDoc, OOP file structure, avoiding eval/extract/compact and type juggling, and preferring core functions over constants. Plan for PHPStan 2.0+ as a prerequisite.

For engineering teams: One composer require --dev, one include, then vendor/bin/phpstan analyze. Start at level 5, baseline existing errors, and block on new ones. Keep the first @param in filter docblocks accurate — the extension treats it as the return type. Use the published examples and the WooCommerce stubs guide for shops. Known rough edge: WordPress's conditional function/class definitions require a sed rename on stubs when functions are already defined; budget a small amount of setup friction for unusual codebases.

Ask: Approve a one-sprint pilot on one representative plugin — measure error count at level 5, fix rate, and CI runtime — with a go/no-go on wider rollout.