Acf Pro Stubs Laravel Package

Technical Evaluation

Architecture fit

• Dev-only stub package: it ships no runtime code, no autoloaded classes, and no service provider. It is a contract surface for static analysis, not an application dependency.
• Fits only codebases that (a) run Advanced Custom Fields PRO and (b) already or plan to run PHPStan, Psalm, or a JetBrains/phpstorm-stubs-aware IDE. For projects not doing static analysis, it delivers nothing.
• Pairs naturally with php-stubs/wordpress-stubs and szepeviktor/phpstan-wordpress; it is not a replacement for either, and it does not pull WordPress stubs transitively.
• Zero footprint in production build artifacts, so architecture risk is confined to the CI/analysis layer.

Integration feasibility

• Very high. Integration is a composer require --dev plus a single scanFiles (or stubFiles) entry in phpstan.neon. No application code changes, no runtime hooks, no migration script.
• Reversible in one commit. Removing the dependency returns the project to its prior state with no data or behavior implications.
• Main friction is not installation but version coupling: ACF PRO is commercial and typically vendored or installed from a private Composer repository, so the stub version must be manually kept in lockstep with the installed ACF PRO version.

Technical risk

• Low overall, but four specific risks:
  • Version drift — stubs generated for ACF 6.x against a project on 6.y (or vice versa) produce false positives/negatives and erode trust in the analysis gate.
  • Stub completeness — ACF's dynamic API (get_field(), have_rows(), flexible content, block registration) returns mixed in most cases; stubs confirm existence and signatures but do not deliver meaningful type inference. Teams expecting deep typing will be disappointed.
  • Licensing ambiguity — ACF PRO is GPLv2+, and stubs are generated from its source; the package declares MIT. Acceptable for a dev-only, non-redistributed dependency, but flag it to legal if stubs are ever vendored into a shipped artifact or a public fork.
  • Bus factor — 74 stars, single primary maintainer, community-supported, no SLA or security response process.

Key questions

1. Which static analysis tool is in use (PHPStan 1.x/2.x, Psalm, IDE-only), and is there an existing baseline?
2. How is ACF PRO installed and version-pinned (private Composer repo, vendored plugin, WP Engine package)? Who owns that pin?
3. What is the supported PHP matrix, and does the stub version align with the ACF PRO version actually deployed?
4. Is szepeviktor/phpstan-wordpress already in the stack? If so, is ACF stub loading configured there or standalone?
5. Does the team accept a community-maintained dev dependency with effectively one maintainer, or does this need an internal fork/vendor policy?

Integration Approach

Stack fit

• PHP 7.4–8.x, PHPStan 1.x/2.x, Psalm 5.x, and JetBrains IDEs via phpstorm-stubs conventions.
• Complements, not replaces, php-stubs/wordpress-stubs. Both should be present for a full WordPress surface.
• Fits any Composer-managed WordPress project (Bedrock, Sage, custom), including monorepos, since it is a leaf dev dependency.

Migration path

• Purely additive and non-breaking. No production code paths, no database changes, no deployment changes.
• Recommended adoption is incremental: add the stub, run analysis, capture a baseline, then ratchet the CI gate rather than blocking on day-one clean output.
• Rollback is deleting one dev dependency and one config block.

Compatibility

• Pin the stub to the ACF PRO major.minor actually installed (e.g., ^6.2 matching ACF 6.2.x); treat stub bumps as part of the ACF upgrade checklist.
• Distinguish ACF free vs PRO surfaces: stubs cover PRO-only functions and classes, so projects on the free plugin will see phantom symbols.
• Ensure the stub file is loaded via scanFiles for symbol discovery or stubFiles if overriding signatures; a misconfigured path fails silently and looks like the package "does nothing."

Sequencing

1. Inventory ACF PRO usage and confirm installed version and install mechanism.
2. Add php-stubs/acf-pro-stubs to require-dev pinned to the matching major.minor.
3. Wire the stub file into phpstan.neon/psalm.xml and verify resolution with a deliberately wrong call.
4. Run analysis and generate a baseline; record the pre/post error delta as the adoption justification.
5. Gate CI on the new baseline and document the ACF-upgrade → stub-bump procedure.
6. Follow up on IDE/autocomplete validation for the team's editors.

Operational Impact

Maintenance

• Near-zero for the package itself; releases track ACF PRO versions (last release 2026-06-01 indicates active, likely automated, publishing).
• The real maintenance load is internal discipline: every ACF PRO upgrade requires a corresponding stub bump and a re-baseline of the analysis gate. Assign that to whoever owns the WordPress dependency updates.

Support

• Community-only, MIT-licensed, effectively one maintainer. No vendor channel, no CVE process, no guaranteed compatibility window.
• If the project is mission-critical for analysis quality, plan for an internal mirror or vendor-of-record policy rather than relying on upstream responsiveness.

Scaling

• Negligible. Dev-only, no runtime, no memory or throughput impact on production.
• CI cost is limited to a modest increase in analysis time and memory from loading an additional large stub file; on very large codebases, watch PHPStan timeouts and memory limits rather than the package itself.

Failure modes

• Silent no-op: stub registered at the wrong path or not included — analysis runs unchanged and the team wrongly concludes the package adds nothing.
• Version drift: stubs ahead of or behind installed ACF PRO → false errors (gate fatigue) or suppressed real errors (false confidence).
• Stub incompleteness: dynamic ACF APIs remain mixed; teams over-trust the gate and skip runtime validation for field access.
• Upstream abandonment: no new stub releases for future ACF versions; mitigated by the stubs being plain PHP and forkable.
• CI instability: memory/timeout failures on large stub sets in constrained runners.

Ramp-up

• Hours, not days. A developer familiar with PHPStan configuration can wire it in and produce a baseline within a single sprint-day.
• The organizational ramp-up is documentation, not skill: publish the version-pinning rule and the upgrade checklist so the stub does not silently drift out of sync with ACF PRO.

TPM recommendation Adopt as a low-cost, low-risk dev-tooling improvement if the team already runs static analysis; value is concentrated in IDE autocomplete and symbol existence, not deep type safety. Do not treat it as a runtime dependency or a substitute for functional testing of ACF field access. The deciding factor is not the package's quality (adequate) but whether the team will commit to version-sync discipline.