Weave Code
Preload Laravel Package
laragear/preload
Laragear Preload helps Laravel apps use PHP OPcache preloading. It generates a preload script, lets you include application and vendor files, and provides Artisan commands to build and refresh the preload list for faster bootstrapping.
Effortlessly create a PHP Preload Script for your Laravel project
Frequently asked questions about Preload
- What does Laragear Preload actually do for a Laravel application?
- Laragear Preload builds a PHP OPcache preload script for your Laravel project as a build-time artifact. It introspects the Laravel container and codebase, lets you include application and vendor files, and ships Artisan commands to generate and refresh the preload list. The resulting preload.php is loaded by OPcache when a PHP process starts, so those classes skip compilation and autoloading on every request.
- How do I install laragear/preload with Composer?
- Install it with Composer, publish the package config file, and run the Artisan command that generates the preload script. Then point opcache.preload in php.ini at the generated file and restart PHP-FPM or reload your long-lived workers. Check the README for the exact command signatures and config keys for the version you install, since they can change between majors.
- Do I need to edit php.ini to use Laragear Preload?
- Yes. The package only produces the preload script; OPcache will not load it unless opcache.preload is set in php.ini, and you may also need opcache.preload_user when the pool runs as root. If your host owns the PHP build and refuses those directives, the package cannot help you regardless of how the script is generated.
- Which Laravel and PHP versions does Laragear Preload support?
- It targets modern Laravel releases on PHP 8.2 and above, running under PHP-FPM or Octane behind a persistent pool. Confirm the exact floors in the package composer.json rather than assuming, because the 4.0.0 release is a major version and the published artifact is only a compare link with no changelog body. A version bump can raise the PHP or Laravel minimum and collide with other packages holding your platform back.
- Does Laragear Preload work with Laravel Octane?
- Yes, Octane is one of the primary workloads this package is aimed at, since preloading pays off most in long-lived workers. The contract worth verifying is how a regenerated preload file interacts with worker recycling and Octane's reload command, because existing workers keep the old preload until they restart. Exercise the reload path in staging before relying on it during a production deploy.
- Can I use Laragear Preload on Laravel Vapor, serverless, or shared hosting?
- No. Preloading requires write access to opcache.preload in php.ini, which most shared hosts, some managed runtimes, and serverless or FaaS platforms including Laravel Vapor do not provide. The package fits containers, VMs, and release artifacts where your team owns the PHP build and the deployment pipeline.
- Will preloading actually make my Laravel app faster?
- Preloading mainly helps high-throughput, long-lived PHP-FPM or Octane workloads with large class graphs, where skipping compilation and autoloading on each request trims bootstrap time. For low-traffic applications the win is marginal relative to the operational surface it adds. Measure before committing: capture opcache_get_status() preload statistics, p50 and p99 latency, worker CPU, and startup memory as a baseline.
- What changed in Laragear Preload v4.0.0 and how do I upgrade from 3.x safely?
- Version 4.0.0 is a major release, which by convention implies breaking changes, but the supplied release artifact is only a compare link without a changelog body, so the exact scope is unverified. That includes minimum PHP and Laravel versions, removed or deprecated config keys, renamed Artisan commands, changed default exclusions, and any Octane integration changes. The safe path is to adopt the current 3.x line first, capture a baseline, then upgrade in a non-production branch, regenerate the preload file, and diff it against the 3.x output to size the blast radius before promoting.
- How do I keep the preload script in sync with deployments and validate it in CI?
- Treat the preload file as a release artifact: regenerate it as a deploy step whenever code changes, and ship it inside the same image or release bundle as the code so each node has a matching pair. If the package emits deterministic output, diff or checksum the generated file in CI and fail the build on unexpected drift before it reaches a node. This matters most on rolling or blue/green releases, where nodes can briefly run mismatched artifacts.
- Why did my PHP-FPM pool fail to start after preloading, and how do I fix OPcache memory errors?
- A malformed or stale preload file is fatal at PHP startup, so the symptom is a dead pool rather than a degraded request, and one bad artifact can take down every worker on the node at once. Preloaded classes are also compiled into the OPcache shared segment and never freed, so an oversized preload list can exhaust opcache.memory_consumption. Validate new output on a single canary node, watch opcache_get_status() preload and memory figures, and avoid bundling preload changes with unrelated upgrades in the same deploy.
Weaver
How can I help you explore Laravel packages today?