Polyfill Apcu Laravel Package

Technical Evaluation

Architecture fit

• This is not a cache backend. It is a name shim: it defines apcu_* functions and APCuIterator by delegating to the legacy apc_* extension. It operates at the PHP global-function layer, beneath Laravel's Cache facade and Illuminate\Cache\ApcuStore.
• There is no service-container, service-provider, or config surface to integrate with. It activates via Composer's files autoload and only defines functions that aren't already defined. Any plan describing registration in AppServiceProvider, or a per-store use_polyfill config key, is describing work this package does not do — that scaffolding would be custom-built and owned by us.
• Architectural fit for a Laravel estate is therefore narrow: only stacks where ext-apc is present and ext-apcu is absent, or where code calls apcu_* directly rather than through the Cache contract. The addressable population inside a supported Laravel install base — 5.1 through 12 all require PHP ≥ 5.5.9, and APC does not run there — is approximately zero.

Integration feasibility

• Installation is trivial (composer require symfony/polyfill-apcu, ~1.5 MB, MIT, no transitive dependencies). That is the only genuinely low-friction part.
• The commonly assumed pitch — "drop-in, zero code change, CACHE_DRIVER=apcu just works" — does not survive scrutiny. extension_loaded('apcu') stays false after the polyfill loads. Laravel's CacheManager guards the apcu driver on that extension check and throws; third-party packages gating on extension_loaded('apcu') or apcu_enabled() bypass the polyfill too. It satisfies function-existence but not capability detection — and capability detection is the common pattern.
• If neither apc nor apcu is present, calls resolve to the polyfill's definitions, which invoke undefined apc_* functions — a fatal Error, not a graceful fallback. This contradicts any "safety net / graceful degradation" framing.
• The API sometimes cited internally (\Symfony\Polyfill\Apcu\ApcuFunctions::register() / isRegistered()) does not exist in the package. Acceptance criteria, test cases, and rollout steps written against it are invalid and must be rewritten before commitment.

Technical risk

• High — false portability claim. The dominant risk is organisational: approving this on "works everywhere" creates a belief that we have portable caching when we do not. It fails later, in production, on the exact hosts it was bought to cover.
• High — performance and semantics drift. Materially higher latency than native APCu on hot paths; per-SAPI, per-pool shared memory; effectively a no-op under CLI, so queue workers, artisan commands, and cache warmers see empty caches while web requests see populated ones. Divergence between workers is a debugging tax, not a defect we can fix.
• Medium — maintenance signal misread. The future-dated 2026-04-11 release and four consecutive "no significant changes" changelogs are artefacts of Symfony's monorepo split-release process, not active development. Zero listed dependents means nobody else is exercising this integration path — that raises, not lowers, integration risk.
• Medium — documentation. The README defers to the polyfill monorepo README; no Laravel-specific guidance, no supported-version matrix, no stated deprecation posture.
• Low — licensing/compliance. MIT, Symfony org, no supply-chain concerns.

Key questions

1. Environment census: across every target deployment, what fraction has ext-apcu, ext-apc, neither? If "neither" is material, this package solves nothing and the initiative closes.
2. Which code calls apcu_* directly — our app, a vendor package, or a config value? What breaks if we refactor that call site instead of shimming it?
3. Is the requirement "APCu compatibility" or "portable caching"? If the latter, the lever is the Cache contract and a driver change, not a function polyfill.
4. Who owns this dependency, and what is the dated exit criterion? A shim with no removal trigger becomes permanent infrastructure debt.
5. Why is a PHP 5.3-era compatibility claim still in the internal pitch when current polyfill releases have a much higher floor? Which source of truth governs go/no-go?
6. If we decline, what is the cost of the alternatives (enforce ext-apcu in the build image; move affected stores to file/database/redis)? That delta is the real business case.

Integration Approach

Stack fit

• Only a fit for the Cache → apcu driver path if we also bypass Laravel's extension guard via a custom Cache::extend registration that skips ensureExtensionIsLoaded. That is unsupported-path engineering; it is our code, our bug, and outside the vendor's support envelope.
• Clean fit when a third-party dependency calls apcu_* directly and cannot be upgraded. In that case the polyfill is a legitimate stopgap — but only on hosts where ext-apc exists, which in practice means hosts we should already be migrating off.
• Poor fit for any stack on Laravel 9+/PHP 8.1+. Symfony retires polyfills as PHP floors rise; plan for abandonment, not adoption. Treat this as a shim that becomes dead weight the moment the vendor raises its floor.

Migration path

• The correct change for a missing ext-apcu is configuration, not a dependency: switch the affected store in config/cache.php and set CACHE_STORE (file/database locally, redis in production). That one-line change is the real migration, measured in hours, not weeks.
• Where a direct apcu_* call exists, wrap it behind Laravel's Cache contract (Cache::store(...)) so the backend becomes an environment decision. This is the durable refactor and it removes the need for the polyfill entirely.
• If the polyfill is currently transitive, the migration is removal: confirm inert, then drop it in the next dependency sweep. No code changes expected.
• Do not plan a phased rollout that "starts with the polyfill and later moves to native APCu" — the polyfill provides no store to migrate from, so there is no intermediate state to be in.

Compatibility

• Verify on the actual target host, not in a spec: php -m | grep -i apc distinguishes apc from apcu from neither, and only the first makes the polyfill functional.
• extension_loaded('apcu') and apcu_enabled() will both report absent; any package or Laravel internals that check capability rather than function existence will behave as if uninstalled.
• APCuIterator exists, but iterates an empty/absent store unless apc_* is backed by real shared memory. Functional smoke tests must assert on stored values, not on class/function existence.
• CLI and FPM are separate memory worlds; test both, and test queue/Horizon workers explicitly.

Sequencing

1. Census: composer why symfony/polyfill-apcu, grep -rn "apcu_" app/ config/, php -m | grep -i apc per environment.
2. Decide the real requirement (portable caching vs. legacy shim) and record it in writing.
3. If caching: change the driver/config first; confirm the app behaves correctly with a cold cache.
4. If a direct apcu_* call site exists and is load-bearing: refactor to the Cache contract.
5. Only then, and only with a dated exit criterion, consider the polyfill as a temporary bridge.
6. Remove or record as knowingly inert; add to the next dependency audit.

Operational Impact

Maintenance

• Low direct cost, non-zero cognitive cost: a Composer dependency that must be explained to every new engineer who assumes it makes APCu work. The "no significant changes" release cadence means upgrade noise without value, plus a future abandonment event when Symfony raises its PHP floor.
• Ownership must be explicit. An unowned shim is permanent debt; assign a named owner and a removal date, or don't add it.

Support

• No vendor support path beyond the monorepo README; no Laravel guidance; no documented sunset policy. Any production issue will be diagnosed by us from first principles.
• Expect recurring support tickets of the form "cache is empty on one worker / after deploy / in the queue" — these are inherent to process-local caching, not fixable by the polyfill, and they consume engineering time disproportionately to the value delivered.

Scaling

• APCu — native or polyfilled — is process-local and per-server. It cannot be a correctness dependency across FPM workers, Horizon consumers, or multiple app instances. Sessions, feature flags, rate-limit counters, and shared state must live in Redis or the database.
• Horizontal scaling makes it worse, not better: more workers means more divergent caches and more confusing cold-cache behaviour. Under CLI it is a functional no-op, so any warm-up strategy built on it appears to work in one context and not the other.

Failure modes

• Fatal Error when neither APC nor APCu is present — the polyfill proxies to undefined apc_*. This is the failure mode most likely to reach production, and it is the opposite of the graceful degradation the shim is often bought for.
• CacheManager throws on the apcu driver because extension_loaded('apcu') remains false — the driver simply won't resolve.
• Silent cache misses / stale-by-worker reads producing intermittent, hard-to-reproduce bugs that get misattributed to application code.
• Post-deploy and post-recycle cold cache — correctness bugs surface only when the store is empty, and are typically found in production rather than CI.
• Abandonment at a future Symfony minor bump, forcing an unplanned change under time pressure.

Ramp-up

• Near-zero to install; substantial to explain and to reason about correctly. The concept engineers must internalise is "this is a function-table shim, not a cache," and the operational rule is "apcu_* is never load-bearing for correctness."
• Onboarding note: Cache::store('file') locally, Cache::store('redis') in production, and treat APCu as a lossy per-process optimisation only.
• Success criteria for the 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.