Should You Use OPcache Preloading in Your PHP App?

Should You Use OPcache Preloading in Your PHP App?

Thinking about enabling OPcache Preloading to squeeze more performance out of your PHP application?

It’s an advanced feature with very specific benefits — and in most cases, you likely won’t notice a difference.

In this post, we’ll explain what OPcache Preloading is, how to set it up, and when (or if) it makes a measurable impact.

What is Preloading?

Preloading was introduced in PHP 7.4, contributed by Dmitry. It allows PHP scripts to be loaded and compiled once at process startup (before any requests), so functions and classes are ready immediately — as if they were built-in.

This is different from regular OPcache, which caches PHP scripts after first execution. Preloading complements OPcache by eliminating autoloading overhead and repeated include/require calls.

The main downside? PHP-FPM or Apache startup time increases, because all preload scripts are executed at once.

When Preloading Makes Sense

Preloading has a few technical pre-requisites:

• Your app is the only one on the server or container
• You’re using PHP-FPM or mod_php
• You can provide a custom preload script

It does not help in setups like Laravel Octane, Roadrunner, FrankenPHP, or AWS Lambda. In fact, it may shift cold start time into boot time with no real net gain.

How to Set Up Preloading

1. Write a preload script This should require all files you want loaded. Symfony does this out of the box. Laravel has third-party support. Or you can write your own. The PHP documentation on Preloading explains the requirements for such a script.
2. Configure php.ini to enable preloading:

When your script from step 1 is called “preload.php” you need the php.ini to point to it. In addition you need to configure the username this script is run with. This should be the same user as the web-server or FPM is running under.

opcache.preload=/app/preload.php
opcache.preload_user=www-data

3. Restart PHP-FPM or Apache Check PHP logs and error tracking (e.g., Tideways) to ensure everything loads cleanly.

What Performance Gains Can You Expect?

In a typical Symfony or Shopware app, autoloading takes around 10–16ms. If the response time of your application is 1 second, preloading might save less than 1%. That’s not worth the complexity.

However, in fast apps that response below 100ms, the story changes.

Example: Tideways Ingest API

We tested preloading on our own application using the pre-generated Symfony preloading script.

The Ingest API receives 30k requests every minute with performance data from our customers. It just authenticates the sender data and then passes it on to a message queue for processing. We expect this API to be very fast to handle the high request volume.

In that case optimizing autoloading performance further will make sense. Before the preloading change we had a 95% percentile response time of 20ms. On average 1ms was spent in autoloading on every request.

After we enabled preloading the 95% response time dropped to 18ms and autoloading time dropped to 0.

That’s a 10% gain.

It will allow us to handle the more of this traffic with fewer resources and save money on server resources.

Conclusion

Preloading isn’t a universal remedy — but in performance-critical, high-throughput environments, it can be worth it.

Use preloading if:

• Your app is well-optimized
• Response times are already low (<100–200ms)
• You want to reduce CPU load at scale to save server resources and increase throughput

For apps with high response times, the relative benefit is negligible. Focus on bigger bottlenecks first.

Need help deciding whether preloading is worth it for your app? Tools like Tideways can measure autoloading and compilation time directly.