Velocity and the opcode cache: why a page costs what it does, and how to measure it #

This page is for administrators who run Exponential Velocity and want to know where the CPU time of a page goes. Two changes belong together (added 2026-10-02):

• Velocity's workers now keep the files the kernel rewrites (INI caches, override caches, compiled templates) in the opcode cache.
• A diagnostic you switch on writes one line per request that says how the request used the opcode cache, so two engines can be compared with numbers.

What was wrong #

PHP's opcode cache does not keep a script that was changed less than opcache.file_update_protection seconds before the request's start. Under PHP-FPM every request starts afresh, so only files written in the last two seconds are skipped. A Velocity worker lives for hours, and its "request start" is the time the worker started. Every file written afterwards (the caches regenerated after a deploy or a cache clear) counted as too new for the whole life of the worker, and was compiled again on every include.

Measured on the demonstration server: the cache served 2.7% of the includes under Velocity against 97% under PHP-FPM, and a rendered page cost 644 ms of CPU against 166 ms.

What changed #

settings/velocity.ini passes opcache.file_update_protection=0 (next to opcache.revalidate_freq=0) to the server process. A file that is still being written is not kept by the cache: the server itself reads an include whole and drops the cache's copy of a file changed in the last two seconds, so nothing half written is served.

No setting of yours needs to change. A restart of Velocity applies it (workers keep what they loaded at warm-up).

Check:

grep -n "opcache\." settings/velocity.ini

Measure it with the opcode cache profile #

The profile is off unless the file var/tmp/opcache_profile.on exists (the kernel does one file_exists() per request to find out). With the file present, every request appends one JSON line to var/tmp/opcache_profile.log.

1. Switch it on and send a few requests to each engine:

touch var/tmp/opcache_profile.on
curl -s -o /dev/null https://<site>/
tail -n 3 var/tmp/opcache_profile.log

2. Read the line of the second and later requests of a process. A worker that keeps its files in the cache shows included_not_cached close to 0; one that compiles them again shows many. Compare it with a PHP-FPM line of the same address.
3. Switch it off again by moving the .on file out of var/tmp/. The log grows with every request while it is on.

Limits #

• Figures belong to the process that answered; compare several lines, not one.
• The profile needs the opcache extension (function_exists('opcache_get_status')).

Related pages #

• Smarty templates: performance (Speed): .stpl pages on Velocity and PHP-FPM, measured
• Velocity persistent worker server
• Velocity response cache
• Static cache generator
• Velocity engines upgrade notes
• Velocity engine settings and programs
• Velocity worker pool and compatibility layer
• Changelog: Exponential Velocity engine
• Upgrade checklist of 1-2 October 2026
• 6.0.15 changelog
• October 2026 chronicle