Acf Pro Stubs Laravel Package

Product Decisions This Supports

• Whether to make static analysis a roadmap commitment. Adding ACF Pro stubs is the cheapest possible proof-of-concept for PHPStan/Psalm adoption in a WordPress codebase. If the team can get ACF-heavy code to level 5 with stubs in place, the case for extending analysis across the plugin/theme portfolio gets much stronger. If the stubs only shift the noise around, that's evidence the real problem is architectural (untyped field access), not tooling — a useful finding either way.
• Build vs. buy on internal type tooling. Two viable paths: (a) consume this package as a dev dependency, or (b) generate stubs in-house from your pinned ACF Pro copy with php-stubs/generator and check them into CI. Buying costs near-zero engineering time and tracks upstream; building costs roughly a day of setup plus regeneration on every ACF upgrade, but removes a third-party dependency and guarantees version parity. The decision hinges on how far your installed ACF version has drifted from the latest stub release.
• Feature scoping around typed field access. Stubs prove that get_field()/the_field() return mixed, so they will not solve the field-value typing problem. Whether to invest in a thin typed accessor layer or generated field value objects is a real roadmap item this package surfaces rather than answers. Use the stub-only baseline to size the residual mixed problem before committing budget.
• Upgrade policy for ACF Pro. Stub release dates are a free leading indicator of how ACF Pro's public API is changing. A flurry of stub releases around an ACF major version is a prompt to schedule the upgrade; a widening gap between your pin and the latest stub release is a signal your analysis baseline is drifting.
• Prioritizing the "undefined function / wrong arity" defect class. ACF conditionally defines its API functions only when the plugin is active, which generates a recurring family of runtime fatals and false-positive IDE warnings. Stubs eliminate the tooling half of that class and let you measure whether the runtime half justifies engineering investment.
• Vendor and dependency-risk review. Dev-only, MIT, not shipped to production. The risk profile is asymmetric in your favor — easy to justify in a security/procurement review, easy to remove if it disappoints.

When to Consider This Package

Adopt when most of these hold:

• ACF Pro is a real dependency of a product you own, and the project is Composer-managed. This is a require-dev package; if ACF Pro is vendored by hand or bundled inside a parent theme, the fit is poor.
• You already run, or are piloting, PHPStan or Psalm in CI and want to raise the level without carving out large ignoreErrors blocks for ACF.
• More than one developer touches field code, or onboarding time matters — IDE autocomplete and signature help for acf_add_local_field_group(), get_field_object(), have_rows(), blocks and options-page APIs is the everyday payoff.
• You're planning a refactor or an ACF major-version upgrade and want the analysis baseline green first.

Look elsewhere or defer when:

• There is no static analysis in the pipeline. Stubs do nothing at runtime; without PHPStan/Psalm/IDE consumption they are dead weight in vendor/.
• The team's actual pain is field value typing. get_field() returning mixed is not something a stub package can fix — evaluate a typed wrapper (custom accessors, generated DTOs, a field-class generator) instead.
• Your ACF version has drifted materially ahead of the latest stub release. Signatures can silently mismatch; treat that as a build-your-own-stubs situation until upstream catches up.
• You lean heavily on third-party ACF add-ons (ACF Extended, third-party blocks, custom field types in plugins). Each needs its own stubs; this package covers core ACF Pro only, so verify coverage of the namespaced/block APIs you actually use against your pin before committing.
• You need coverage of the JS/React block editor or REST surfaces. Out of scope.

How to Pitch It (Stakeholders)

One line: a free, MIT-licensed, development-only type-definition package that teaches our static analyzer and IDE the shape of the Advanced Custom Fields Pro API — no runtime code, no production footprint.

To executives: This is a zero-cost, near-zero-risk lever on code quality for the ACF portions of our WordPress products. It changes nothing in production; it lets our tooling catch a recurring class of "undefined function" and "wrong arguments" bugs before merge, and it shortens onboarding for developers who don't know ACF's API by heart. The main risk is upstream maintenance — the project is small (74 stars, no registered dependents, though private agency repos typically aren't counted) — which we mitigate by pinning the version, keeping the integration to a single require-dev line plus a small analyzer config entry, and retaining the option to generate the stubs ourselves in about a day if the package stalls.

To engineering: Add php-stubs/acf-pro-stubs to require-dev and reference it via stubFiles/scanFiles in phpstan.neon, alongside php-stubs/wordpress-stubs. Expect immediate wins on undefined-function and parameter-count errors and IDE autocomplete across the ACF API. Be explicit about the boundary: this gives us signatures, not field types — get_field() stays mixed. If we want typed field access, that's a separate decision about a wrapper layer, and this baseline is exactly the data we need to scope it. Watch the version-parity caveat on ACF upgrades, and budget sibling stubs for any ACF add-ons we adopt.