OPcache

OPcache keeps compiled PHP code in shared memory, so PHP does not parse every file on every request. The admin page Tools / OPcache (?object=manage_opcache) shows how the cache of the site is doing, which settings are risky, which scripts are cached, and lets a super-admin reset it, invalidate a script or a folder, or compile a file. The engine is _class('admin_opcache') (yf_admin_opcache, plugin cache); it reads OPcache through _class('opcache_api'), a small wrapper of the opcache_*() functions. No extra library is used.

Which cache you see

Every PHP process type has its own OPcache. The page shows the cache of the PHP that serves the admin, normally PHP-FPM, which is the cache your visitors use too (one FPM pool shares one cache). The console (php on the command line, cron jobs) has a separate cache that lives only as long as each command, and only when opcache.enable_cli=1; resetting it from the page is not possible and not needed. The built-in server (php -S) has a cache of its own too; it follows opcache.enable (not enable_cli) of the php.ini it starts with, for example php -d opcache.enable=1 -S ....

The page

  • Overview: cards for the state (enabled, JIT on or off and its mode, the file cache, validate_timestamps and revalidate_freq), memory used / free / wasted with a bar, the interned strings buffer, keys used of max_accelerated_files, hit rate with hits and misses, restarts (out of memory, out of keys, manual) and the last restart, start time and uptime, and the JIT buffer when JIT is on. The ⟳ button refreshes the cards every 5 to 60 seconds; it is off until you choose an interval, and the choice is kept for you. Below the cards: the checks, the invalidate and compile forms, and the folders that use most memory.
  • Configuration: every opcache.* directive with its value; the risky ones are highlighted with why and how to fix.
  • Scripts: the cached scripts with their path relative to APP_PATH (app:) or YF_PATH (yf:), hits, memory, last use and file time. Sort by any column, filter by a part of the path, 50 a page; the table is paged on the server, so thousands of scripts are fine. Each row has an Invalidate button.
  • Folders: the folders of the cached scripts at a depth of 1 to 6, most memory first, as a bar split by folder and a list where each folder opens to its subfolders; Invalidate on a folder invalidates every cached script below it.

Checks

CheckWhy it matters
Cache full, memory almost full, low memory_consumption (under 128 MB), restarts out of memoryA full cache stops caching new scripts; a restart empties it and every script is compiled again.
Wasted memory above max_wasted_percentageMemory of changed scripts is not reused; OPcache restarts once the cache is full. Reset after a deploy.
Keys near max_accelerated_files, restarts out of keysAt the limit new scripts are not cached. Use 20000 or more for a site with the framework.
validate_timestamps=1 with revalidate_freq=0 on productionA stat() of every included file on every request. Use validate_timestamps=0 and reset after each deploy, or revalidate_freq=60.
validate_timestamps=0 on developmentEdits do not show until a reset.
Interned strings buffer almost full, JIT buffer almost full, low hit rateMore memory per worker, less machine code, more compiling.
save_comments=0Doc comments are dropped from cached code: code that reads them sees none.

Production or development is decided as for the site doctor (yf_admin_doctor::$ENVIRONMENT, else the host name). The doctor's OPcache check links its findings to this page.

Reset, invalidate, compile

  • Reset (opcache_reset()) empties the whole cache; scripts are compiled again on their next use.
  • Invalidate (opcache_invalidate($file, true)) marks one script stale, or with whole folder every cached script below a folder.
  • Compile (opcache_compile_file()) parses a .php file into the cache without running it.

Paths are written as app:modules/news.class.php, yf:plugins/cache, a path relative to APP_PATH (then YF_PATH), or a full path. Only paths inside APP_PATH or YF_PATH are accepted, after realpath() (a link out of them is refused), and never with . or .. parts. A deleted file that is still cached can be invalidated by its old path. Every change is a POST with the session token and a confirm; a plain link (GET) only shows a confirm form, a script (ajax) gets 403. Each change writes a row to the admin wall (Logs / Admin / Activity).

Access and settings

Super-admins (group 1) only; a block rule does not open the page to other groups. Lists and messages write paths as app: / yf:, but the Configuration tab (opcache.preload, opcache.file_cache, opcache.error_log...) and the restrict_api message show full server paths: they are for super-admins only. Settings page, tab Admin tools: OPcache page read-only (manage_opcache.READ_ONLY) hides and refuses the changes. In code:

$PROJECT_CONF['manage_opcache'] = [
    'READ_ONLY' => false,     // true: status only
    'PER_PAGE' => 50,         // scripts a page
    'REFRESH_DEFAULT' => 0,   // seconds between card refreshes until an admin chooses (0 = off)
];
$PROJECT_CONF['admin_opcache'] = [
    'MEMORY_MIN_MB' => 128,   // lower memory_consumption is reported
    'KEYS_WARN_PERCENT' => 90,
    'ENVIRONMENT' => null,    // 'production' or 'development'; null: as the doctor detects it
];

When there is nothing to show

  • Not loaded: install the extension (php-opcache on most systems) and turn it on, see below.
  • Loaded but off: opcache.enable=0 (or opcache.enable_cli=0 for the command line).
  • opcache.restrict_api: PHP refuses the OPcache functions to scripts whose path does not start with that value. The page says so, shows the php.ini values, and refuses the changes; set it to a folder that holds the admin, or leave it empty.

A good start for production, in the php.ini of PHP-FPM (for example conf.d/10-opcache.ini), then restart PHP-FPM:

zend_extension=opcache
opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=20000
opcache.validate_timestamps=0   ; reset OPcache after each deploy
opcache.save_comments=1