Preload Laravel Package

Technical Evaluation

Architecture fit. Laragear/Preload operates at the PHP/OPcache layer rather than the request path: it introspects the Laravel container and codebase to emit a preload.php artifact that OPcache loads at process start. Architecturally this is a build-and-deploy-time concern, not a runtime dependency, which makes it compatible with immutable-artifact and containerized pipelines but incompatible with any environment where you cannot set opcache.preload in php.ini (most shared hosting, some managed runtimes, and serverless/FaaS platforms including Vapor). The value is concentrated in high-throughput, long-lived PHP-FPM or Octane workloads with large class graphs; for low-traffic apps the win is marginal relative to the operational surface it adds.

Integration feasibility. Installation is conventional Composer plus a published config file and an artisan generate step, so a Laravel team of any seniority can wire it in. The real gating items are infrastructure-side: write access to php.ini, ownership of opcache.preload_user when the pool runs as root, and a deploy hook that regenerates the preload file after code changes. v4.0.0 is a major version, which by convention implies breaking changes; the supplied release artifact is only a compare link with no changelog body, so the actual scope (minimum PHP/Laravel versions, config key renames, artisan command signature changes, Octane integration changes, deprecations) is unverified.

Technical risk. Elevated and asymmetric. A malformed or stale preload file is fatal at PHP startup, meaning the failure mode is a dead pool rather than a degraded request — one bad artifact can take down every worker on a node simultaneously. Major-version upgrades compound this because generated-output shape and config schema can shift without any runtime signal until the next deploy. Secondary risks: OPcache shared-segment exhaustion (opcache.memory_consumption) since preloaded classes are never freed, and preload files drifting out of sync with deployed code on rolling or blue/green releases where nodes briefly run mismatched artifacts.

Key questions to resolve before any decision.

1. What is the actual v4.0.0 diff — minimum PHP and Laravel versions, removed/deprecated config keys, renamed commands, changed default exclusions?
2. Does a documented upgrade guide exist, and was 3.x given a supported-window or LTS commitment?
3. Is the Octane integration contract unchanged, specifically how preload interacts with worker recycling and octane:reload?
4. What is the maintenance signal — release cadence, open-issue backlog, single-maintainer concentration, PHP 8.4/8.5 forward compatibility?
5. Does the package emit anything we can diff deterministically in CI (stable ordering, checksum) so we can validate generated output before it reaches a node?

Integration Approach

Stack fit. Appropriate for Laravel 10/11/12 on PHP 8.2+ running PHP-FPM or Octane behind a persistent pool, with CI/CD control over the image or release artifact. Poor fit for serverless, multi-tenant shared hosting, or any environment where the platform owns the PHP build and refuses opcache.preload.

Migration path. Treat this as a two-phase change and do not couple it to the v4 upgrade. Phase one: adopt whatever 3.x line is currently installable, generate the preload file, and capture a baseline — opcache_get_status() preload stats, p50/p99 latency, worker CPU, and startup memory. Phase two: upgrade to 4.0.0 in a non-production branch, regenerate, and diff the emitted preload file against the 3.x output to size the blast radius. Only then promote.

Compatibility. Build an explicit matrix and pin it in the ADR: PHP minor, Laravel major, Octane version, distro OPcache build, opcache.preload_user, opcache.memory_consumption, and the class-count ceiling at which the segment saturates. If v4 raises the PHP floor or drops older Laravel majors, this collides with any other package still holding the platform back — sequence that constraint first.

Sequencing.

1. Confirm infrastructure ownership of php.ini and preload_user; get written sign-off.
2. Add generate-and-diff to CI so the artifact is validated, never hand-edited.
3. Validate boot with php -d opcache.preload=<artifact> -d opcache.enable_cli=1 -v in the pipeline.
4. Canary a single node for at least one full traffic cycle; compare OPcache hit rate and startup memory.
5. Roll to the fleet; keep the previous php.ini one deploy behind for instant rollback.
6. Only after the pipeline is boring, upgrade the package from 3.x to 4.0.0 as a separate, independently revertible change.

Operational Impact

Maintenance. Small surface area, but a major bump is scheduled work, not a composer update. Budget the upgrade against a real ticket with a rollback plan. The generated preload file should be a build artifact, not committed to the repository — committing it creates a second source of truth that silently rots.

Support. This shifts a class of failures from "application error in logs" to "deploy fails and nothing is in the logs," because a fatal OPcache preload error kills the worker before Laravel's logger initializes. The on-call runbook must start with php -d opcache.preload=... -v and a check of opcache_get_status()['preload_statistics'], not with application log triage. Most Laravel developers will not know this reflexively.

Scaling. Returns improve with class count and requests-per-second; preloading removes per-worker recompilation of a stable class graph. Costs are front-loaded: preloaded classes live in the shared OPcache segment permanently, so raising opcache.memory_consumption is usually required and must be sized against the container memory limit. Under Octane this is more valuable (fewer, longer-lived workers mean less repeated compile) but also less forgiving of a bad artifact, since all workers on a node load the same file.

Failure modes to pre-plan.

• Fatal at startup from a preload file referencing missing classes, extensions, or unresolvable autoload paths.
• OPcache segment exhaustion after the class graph grows past the configured ceiling.
• Artifact drift during rolling deploys where old and new code coexist.
• preload_user mismatch when the pool runs as root, causing silent no-op rather than failure — the worst case, because you believe preloading is active when it is not.
• Octane workers continuing to serve from a stale preload until octane:reload or a full restart.

Ramp-up. Roughly one engineer-day for a Laravel developer to stand up generation and CI validation, plus platform or infrastructure sign-off for php.ini changes and memory sizing — realistically one to two weeks elapsed end to end. This is an optimization to schedule after traffic justifies it, not a day-one dependency. Given that v4.0.0 shipped with no human-readable changelog in the artifact provided, hold the upgrade decision until the diff and upgrade guide are reviewed.