Wp Cli Stubs Laravel Package

Technical Evaluation

Architecture fit

• The package is a collection of declaration-only PHP stub files for WP-CLI functions and classes. It ships no executable code, no service provider, no framework bindings, and imposes no runtime dependency on a Laravel application.
• Fit with a Laravel codebase is conditional, not native. Laravel does not consume WP-CLI; the package only becomes relevant where the PHP estate includes WordPress/WP-CLI code — most commonly agency monorepos, hybrid Laravel + WordPress product suites, or shared packages that shell out to or extend WP-CLI commands.
• Consumed exclusively as a require-dev artifact and wired into static analysis (PHPStan scanFiles / stubFiles, or Psalm stubFiles). It is an analysis-time contract, not an integration surface.

Integration feasibility

• Extremely low effort: one Composer dev dependency, one or two config lines, and a CI re-run. No application code changes, no migrations, no runtime risk.
• Complements php-stubs/wordpress-stubs in the same family, which is the realistic adoption path — teams rarely add this package in isolation.
• No Laravel service provider, facade, or config publishing is required or expected, so there is no framework-version coupling to manage.

Technical risk

• Low blast radius, low upside. Because it is dev-only, the worst case is a broken analysis pipeline, not a production incident.
• Staleness risk is the primary concern. Stubs are a manually regenerated mirror of the WP-CLI API. Version drift against the WP-CLI release the team actually targets produces false negatives (unflagged calls to removed functions) or false positives (undefined-symbol errors on newer APIs).
• Duplicate-declaration risk when stub sets overlap or when WP-CLI code paths are loaded both via Composer autoload and scanFiles.
• Community validation is thin — 30 stars, 0 dependents — so the maintenance signal is weak and there is no implied user base to surface regressions.

Key questions

• Do we actually maintain WP-CLI commands, or is this a hypothetical need? If no WP-CLI code exists, the correct decision is to defer.
• Which WP-CLI major/minor version does our deployment target, and which version does this stub release track?
• Are we standardizing on PHPStan or Psalm? The wiring differs and should match the existing CI gate.
• Do we have a monorepo boundary that justifies a shared static-analysis baseline, or is this a single-team tool?
• Who owns periodic stub regeneration, and is there a versioning policy tying stub bumps to WP-CLI upgrades?

Integration Approach

Stack fit

• Best fit: a polyglot PHP monorepo where Laravel services and WordPress plugins/CLI tooling live under one Composer root and one static-analysis configuration. Here the marginal cost is near zero and the coverage gain is real.
• Poor fit: a pure Laravel application with no WordPress surface. Adopting it there adds configuration noise with no analysis benefit and should be explicitly rejected.
• Acceptable fit: a Laravel package or internal library that provides WP-CLI command scaffolding, where downstream consumers benefit from accurate types.

Migration path

• Add as a require-dev entry with a pinned constraint aligned to the WP-CLI version in use.
• Register the stub path in the existing PHPStan/Psalm config rather than introducing a second analysis tool.
• Run analysis before and after; the delta is the true value signal. If the delta is empty, the package is not earning its place and should be removed.
• Generate or refresh the baseline in the same PR so the gate flips cleanly.

Compatibility

• Verify PHP language level, PHPStan/Psalm major version, and WP-CLI API surface all line up. The package is a passive file set, so incompatibility manifests as parse errors or unresolved symbols rather than runtime failures.
• Watch for coexistence with wordpress-stubs; overlapping declarations of WP-CLI-adjacent WordPress functions are the most likely source of friction.
• No conflict with Laravel's own tooling (Pint, PHPStan/Larastan) provided stub registration is scoped to the relevant paths.

Sequencing

1. Inventory WP-CLI usage across the estate and confirm the target WP-CLI version.
2. Pin the dev dependency and register stubs in the analysis config.
3. Run analysis, triage the delta, and record whether it surfaced real defects.
4. Add the CI gate and document the stub-bump procedure alongside WP-CLI upgrade steps.
5. Re-evaluate at the next WP-CLI major upgrade; drop the dependency if the delta stays empty.

Operational Impact

Maintenance

• Ongoing cost is small but non-zero: someone must bump the stub version when WP-CLI upgrades and re-baseline the analysis output. Without a named owner this silently rots.
• The package itself is a generated artifact, so maintenance burden shifts to verifying upstream freshness rather than patching code.
• No security surface — dev-only declarations with no runtime execution path, so it should never appear in vulnerability triage or dependency-scanning gates beyond license checks.

Support

• MIT license, community-maintained, single-maintainer risk profile. No vendor SLA, no support channel, no deprecation policy.
• Given 0 dependents, we would be an early adopter bearing the cost of discovering breakage. Budget for the possibility of forking or vendoring the stubs if upstream stalls.
• Acceptable for a dev-tooling dependency; not acceptable if any workflow makes production correctness depend on it.

Scaling

• Scales trivially — it is a static file set with no runtime footprint, no memory cost, and no per-request impact. Analysis time grows marginally with stub volume.
• Works identically for one team or fifty; the only scaling concern is config sprawl across multiple analysis roots in a large monorepo.

Failure modes

• Stale stubs: analysis passes against an API that no longer exists in the deployed WP-CLI version — the most dangerous failure because it is silent.
• Version skew: stub release out of step with the target WP-CLI version yields false errors that push engineers to suppress rather than fix, eroding trust in the gate.
• Declaration collisions: duplicate symbols with wordpress-stubs or autoloaded code break analysis outright.
• Upstream abandonment: no updates, forcing a fork or removal at the next WP-CLI upgrade.
• Gate erosion: if the stub delta is noisy, teams add blanket ignores and the static-analysis investment degrades across the whole repo.

Ramp-up

• Near-zero for engineers already fluent in PHPStan/Psalm stub configuration; it is a config-file change, not a new tool.
• The real ramp-up is organizational: documenting why the dependency exists, which WP-CLI version it mirrors, and the bump procedure. Without that, the next engineer to touch CI will remove it as unexplained.
• Recommend a short ADR capturing the decision, the pinned version, and the drop condition — this is the artifact that makes a low-signal, low-cost dependency defensible rather than accidental.