Preload Laravel Package

Product Decisions This Supports

• Latency/throughput investment: OPcache preloading compiles hot classes once at server start instead of per request (or per worker recycle). A PM frames this as a p95/p99 latency and requests-per-node lever, not a feature — the decision is "do we spend engineering days on a perf initiative, or on product work?"
• Build vs buy vs ignore: this package replaces a hand-rolled preload-script generator (usually a bespoke script parsing the Composer classmap). Adopt it, or accept that nobody on the team will maintain the bespoke version.
• Capacity and cost planning: if a validated gain lands (commonly single-digit to low-double-digit % on bootstrap-heavy apps), it feeds node sizing, autoscaling floor, and cloud spend forecasts. Treat any number as unproven until a load test on a representative environment says otherwise.
• Roadmap sequencing: a natural "cheap win" candidate for a performance-themed sprint, or a fill-in task — but it has a hard prerequisite (server-level opcache.preload control), so it belongs behind any roadmap item that assumes platform migration.
• Deployment pipeline decisions: adoption means adding a generate-preload-artifact step to CI/CD and a restart step to release runbooks. That is an ops-owned decision with ongoing cost, not a one-off install.
• Use cases where it applies: high-RPS APIs, latency-sensitive endpoints, large monoliths with big classmaps, apps where profiling shows autoload/compile time as a visible slice of request time.

When to Consider This Package

Consider it when:

• You control PHP runtime config: opcache.preload is an ini directive requiring a server restart and, typically, root or platform-level access. No ini control, no benefit.
• You're on a supported PHP/Laravel combination. v4.0.0 is a major bump and the release notes are only a changelog link — treat it as containing breaking changes until engineering confirms. Pin v3.0.1 if already in use; upgrade only after reading the diff and testing.
• Profiling shows compilation/autoload overhead is material. If time is dominated by DB, network, or external APIs, expected gain is marginal and the effort is better spent elsewhere.
• Your deploy process is deterministic: the generated preload list must be regenerated whenever dependencies change, or stale references can hard-fail workers at startup.
• Your dependency graph is reasonably stable; frequent package churn means regeneration churn and repeated verification.

Look elsewhere when:

• You're on serverless or short-lived-process platforms (Vapor, most container-per-request setups) where there's no long-lived worker to preload into.
• You're on shared hosting or a managed platform that won't expose opcache ini settings.
• The app is small enough that bootstrap cost is noise.
• You just want cheaper wins: raising opcache.memory_consumption, tuning realpath_cache, or disabling validate_timestamps in production are lower-effort levers to try first.
• Nobody owns server configuration — a preload script nobody regenerates is a latent outage.

How to Pitch It (Stakeholders)

For executives: A small, low-risk, no-license-cost optimization that can improve response times and reduce the number of servers needed to serve the same traffic. Blast radius is contained: rollback is removing one ini line and restarting. The ask is a timeboxed spike — profile, generate the preload list, run a before/after load test — and we commit to infra or sizing changes only if the measured gain justifies the operational overhead. No new vendor, no commercial dependency.

For engineering: One Artisan command generates the preload list from the compiled classmap; wire it into the build and restart step of deploy. Expect the gains to come from skipping per-request compilation and classmap lookups. Main risks are (1) a stale preload list after a dependency change causing startup fatals — mitigate by generating at build time, never hand-editing; (2) opcache memory ceilings — watch opcache_get_status(); (3) the opcache.preload_user requirement under PHP-FPM. v4.0.0 is a new major release whose notes are only a changelog link — treat it as breaking, review the diff, and default to v3.0.1 for any immediate rollout. Ship behind measurement: capture p50/p95/p99 and RPS-per-node before and after on production-like data, then decide whether it stays.