From 83c41a8f69bacceef42fb99b2188bb8b24b2fe58 Mon Sep 17 00:00:00 2001 From: Christoph Michael Becker Date: Thu, 30 Jul 2020 08:21:47 +0000 Subject: [PATCH] Document configuring opcache preloading Patch provided by Larry Garfield. git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@350245 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/opcache/book.xml | 1 + reference/opcache/preload.xml | 121 ++++++++++++++++++++++++++++++++++ 2 files changed, 122 insertions(+) create mode 100644 reference/opcache/preload.xml diff --git a/reference/opcache/book.xml b/reference/opcache/book.xml index 3d3162940d42..548bad8bbd65 100644 --- a/reference/opcache/book.xml +++ b/reference/opcache/book.xml @@ -20,6 +20,7 @@ &reference.opcache.setup; + &reference.opcache.preload; &reference.opcache.reference; diff --git a/reference/opcache/preload.xml b/reference/opcache/preload.xml new file mode 100644 index 000000000000..c8e14b5c5043 --- /dev/null +++ b/reference/opcache/preload.xml @@ -0,0 +1,121 @@ + + + + Preloading + + + As of PHP 7.4.0, PHP can be configured to preload scripts into the opcache when the engine + starts. Any symbols (functions, classes, etc.) in those files will then become + globally available for all requests without needing to be explicitly included. That trades + convenience and performance (because the code is always available) for baseline memory usage. It also + requires restarting the PHP process to clear pre-loaded scripts, meaning this feature is + only practical to use in production, not in a development environment. + + + + Note that the optimal tradeoff between performance and memory may vary with the application. + "Preload everything" may be the easiest strategy, but not necessarily the best strategy. Additionally, + preloading is only useful when there is a persistent process from one request to another. That means + while it can work in a CLI script if the opcache is enabled, it's generally pointless. The exception + is when using preloading on FFI libraries. + + + + + Preloading is not supported on Windows. + + + + + Configuring preloading involves two steps, and requires that the opcache be enabled. + First, set the opcache.preload + value in &php.ini;: + + + + + + + + + + preload.php is an arbitrary file that will run once at server startup + (PHP-FPM, mod_php, etc.) and load code into persistent memory. If PHP will be run as + root (not recommended), the opcache.preload_user + value can specify an alternate system user to run the preloading. Running preloading as + root is not allowed. + + + + In the preload.php script, any file referenced by include, + include_once, require, require_once, or + opcache_compile_file will be parsed into persistent memory. In the following example, + all .php files in the src directory will be preloaded, unless they + are a Test file. + + + + + $file) { + require_once($file[0]); +} +?> +]]> + + + + + Both include and opcache_compile_file will work, but have different + implications for how code gets handled. + + + include will execute code in the file, + while opcache_compile_file will not. That means only the former supports + conditional declaration (functions declared inside an if-block). + Because include will execute code, nested included + files will also be parsed and their declarations preloaded. + opcache_compile_file can load files in any order. That is, if + a.php defines class A and b.php defines class + B that extends A, then opcache_compile_file can + load those two files in any order. When using include, however, a.php + must be included first. + In either case, if a later script includes a file that has already been preloaded then + its contents will still execute, but any symbols it defines will not be re-defined. Using + include_once will not prevent the file from being included a second time. + + + Which approach is better therefore depends on the desired behavior. With code that would otherwise use an + autoloader, opcache_compile_file allows for greater flexibility. With code that would + otherwise be loaded manually, include will be more robust. + + + + +