Polyfill Apcu Laravel Package

Product Decisions This Supports

• Close the "APCu compatibility" workstream as won't do. This package is not a cache. It is a name-shim that defines apcu_* functions and APCuIterator by delegating to the legacy apc_* extension. It only has effect on a host running the deprecated APC extension, which does not exist on PHP 5.5+. Every Laravel version in service (5.1 through 12) requires PHP ≥ 5.5.9, so the addressable population in our install base is approximately zero. The decision this supports is a kill, not a backlog item.
• Choose the cache driver on capability, not portability. When a feature needs caching, the PM decision is Redis / database / file — never "APCu so it works everywhere." The remedy for a missing ext-apcu is a one-line CACHE_STORE change, not a dependency. Adopting this for portability yields no working cache and a false sense of coverage.
• Decide which store owns sessions, config hints, and feature flags. APCu — native or polyfilled — is process-local. It cannot be a correctness dependency across FPM workers, Horizon/queue consumers, or multiple app servers. Decision of record: sessions and shared state live in Redis or the database; APCu may only ever be a per-process, lossy optimisation.
• Set the hosting-tier support policy explicitly. If a customer segment runs shared hosting without APCu, the product answer is graceful degradation (file/database cache) or a documented Redis requirement — not a compatibility shim. This package supports the "documented requirement" branch, which is cheaper to operate.
• Dependency hygiene and removal planning. This is an auto-split, auto-released Symfony monorepo package: four consecutive releases (v1.34–v1.37) with the literal changelog "no significant changes," zero listed dependents, and an inert footprint. The plan of record should be confirm inert, then remove — budgeted as a small cleanup ticket, not a migration project.
• Roadmap non-commitment. Keep this off the roadmap narrative. It is not a compatibility enabler that unlocks features; it removes a blocker that only existed on Laravel 4.2/5.0-era stacks running PHP 5.4.
• Due-diligence precedent. The vendor's broader summary ("environments where native APCu support may be missing") overstates the README's actual scope ("to users of the legacy APC extension"). That gap justifies a standing rule: any polyfill or shim adoption requires a one-hour spike with written verification before it enters composer.json.

Decision summary

When to Consider This Package

Adopt only when all of the following hold:

1. Production PHP is ≤ 5.4 with the legacy APC extension loaded (Laravel 4.2 / 5.0 era).
2. A PHP upgrade is genuinely blocked (hosting contract, compliance, frozen vendor image) and is not on the 12-month roadmap.
3. Application or third-party code calls apcu_* functions directly, and refactoring to the Cache facade is out of scope for the current horizon.
4. The cached data is non-critical and process-local by nature (config hints, feature-flag snapshots), so losing it on a worker recycle is acceptable.

It is also acceptable to leave it in place as an unexamined transitive dependency — don't spend cycles on it; confirm it is inert on the target PHP version and note it for the next composer audit.

Look elsewhere if:

• ext-apcu simply is not installed on PHP 7.x/8.x. The polyfill supplies no store; ApcuStore will still be empty. Fix the driver, not the function table.
• Performance matters. Native APCu is in-process; any shim adds indirection on top of a store you do not have.
• You need shared state across web and queue workers, or across multiple servers — use Redis/Memcached/DynamoDB.
• You need atomicity or correctness guarantees: locks, rate limiters, counters (apcu_inc, apcu_cas) under concurrency.
• You are on Laravel 9+ / PHP 8.1+. Symfony retires polyfills as PHP floors rise; plan for eventual abandonment rather than dependency.
• Anything security-sensitive is cached (no encryption, no TLS, no access control).

Adoption checklist before any commit: grep -rn "apcu_" app/ config/ vendor/ to see whether usage is real; composer why symfony/polyfill-apcu to see who pulled it in; php -m | grep -i apc on the actual target host; confirm store selection in config/cache.php and config/session.php; write down what breaks when the cache is empty. Note also that extension_loaded('apcu') stays false after the polyfill loads — Laravel's CacheManager guards the apcu driver on that check, so CACHE_DRIVER=apcu will still throw. The polyfill satisfies function existence, not capability detection.

How to Pitch It (Stakeholders)

For executives / business leaders

"We evaluated symfony/polyfill-apcu for [initiative]. Recommendation: do not adopt, and remove it if it is already in our dependency tree. It is a compatibility shim for PHP 5.4-era servers running the deprecated APC extension — a population we no longer support, since our minimum PHP is [X]. It does not make caching work where APCu is absent; the vendor's own README limits it to legacy-APC users, and Laravel's APCu driver still refuses to start because the extension check fails. Adopting it adds a dependency and a false sense of portability. The real fix — routing caching through Redis or file cache via one environment variable — is hours of work, not weeks. Ask: approve closing the APCu compatibility ticket as won't-do and reallocate that effort to [caching/performance initiative]."

For engineering leads

"symfony/polyfill-apcu is a proxy, not an implementation: it maps apcu_* onto the legacy apc_* functions. Consequences: no storage on PHP 7/8, no benefit on shared hosting, no performance win, and it becomes dead weight the moment Symfony raises its PHP floor — it is already issuing releases with 'no significant changes' and has zero listed dependents. Keep it out of composer.json deliberately. If a teammate proposes it for 'APCu portability,' the correct change is config/cache.php plus CACHE_STORE. If it is already transitive, verify it is inert and schedule removal in the next dependency sweep. Next steps: (1) composer why symfony/polyfill-apcu; (2) grep -rn "apcu_" app/ config/; (3) php -m | grep -i apc on the target host; (4) if the answer is 'no native APCu,' switch the affected store and delete the ticket."

For developers

"Don't add this to fix a missing ext-apcu. It has no cache of its own — it just forwards to apc_*, and if neither extension is present those calls fatal rather than degrade gracefully. extension_loaded('apcu') remains false, so Cache::store('apcu') still throws and any package gating on apcu_enabled() bypasses the shim entirely. If you need a cache that always works: Cache::store('file') locally, Cache::store('redis') in production, and never let apcu_* be load-bearing for correctness. If you genuinely need APCu semantics on an already-APCu-enabled host, use the native extension and let Laravel's ApcuStore do its job. Keep the polyfill out of hot paths and out of new code entirely."

Success criteria for this decision: no application code depends on apcu_* for correctness; every environment has a cache driver that works without ext-apcu; the package is either absent from composer.json or recorded as knowingly inert.