[doc-en] master: opcache: document always-built-in and file_cache_read_only (8.5) (#5881)

Author: Louis-Arnaud (lacatoire) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-11-10T09:02:56+01:00 Commit: https://github.com/php/doc-en/commit/6fad47c6ec034be2050771ab0213af06936219dc Raw diff: https://github.com/php/doc-en/commit/6fad47c6ec034be2050771ab0213af06936219dc.diff opcache: document always-built-in and file_cache_read_only (8.5) (#5881) * opcache: document PHP 8.5 always-built-in change and file_cache_read_only * Restore the original xmlns attribute order in opcache/configure.xml * opcache: document that opcache.memory_consumption cannot be changed once set up Changed paths: M reference/opcache/configure.xml M reference/opcache/ini.xml Diff: diff --git a/reference/opcache/configure.xml b/reference/opcache/configure.xml index 571849662fe6..76f5596bef33 100644 --- a/reference/opcache/configure.xml +++ b/reference/opcache/configure.xml @@ -4,17 +4,27 @@ &reftitle.install; <simpara> - OPcache can only be compiled as a shared extension. If you have - disabled the building of default extensions with - <option role="configure">--disable-all</option>, you must compile PHP with - the <option role="configure">--enable-opcache</option> option for OPcache - to be available. + As of PHP 8.5.0, OPcache is always built into the PHP binary and is always + loaded. The <option role="configure">--enable-opcache</option> and + <option role="configure">--disable-opcache</option> configure flags have been + removed, and PHP no longer produces <filename>opcache.so</filename> or + <filename>php_opcache.dll</filename> files. + Using <literal>zend_extension=opcache.so</literal> or + <literal>zend_extension=php_opcache.dll</literal> INI directives will emit + a warning. + The <link linkend="ini.opcache.enable">opcache.enable</link> and + <link linkend="ini.opcache.enable-cli">opcache.enable_cli</link> INI + directives are still honored to control whether OPcache is active. </simpara> <simpara> - Once compiled, you can use the + Prior to PHP 8.5.0, OPcache could only be compiled as a shared extension. + If you had disabled the building of default extensions with + <option role="configure">--disable-all</option>, you had to compile PHP with + the <option role="configure">--enable-opcache</option> option for OPcache + to be available. Once compiled, you could use the <link linkend="ini.zend-extension">zend_extension</link> configuration - directive to load the OPcache extension into PHP. This can be done with + directive to load OPcache with <literal>zend_extension=/full/path/to/opcache.so</literal> on non-Windows platforms, and <literal>zend_extension=C:\path\to\php_opcache.dll</literal> on Windows. diff --git a/reference/opcache/ini.xml b/reference/opcache/ini.xml index 616cb6d3e257..b4965c0c0978 100644 --- a/reference/opcache/ini.xml +++ b/reference/opcache/ini.xml @@ -226,6 +226,12 @@ <entry><constant>INI_SYSTEM</constant></entry> <entry>Windows only.</entry> </row> + <row> + <entry><link linkend="ini.opcache.file-cache-read-only">opcache.file_cache_read_only</link></entry> + <entry>0</entry> + <entry><constant>INI_SYSTEM</constant></entry> + <entry>Available as of PHP 8.5.0.</entry> + </row> <row> <entry><link linkend="ini.opcache.validate-permission">opcache.validate_permission</link></entry> <entry>0</entry> @@ -417,6 +423,11 @@ silently falls back to regular pages when the operating system has not set aside enough of them. </simpara> + <simpara> + As of PHP 8.5.0, changing this directive once OPcache is set up fails and + logs a warning, for example when using <literal>php_admin_value</literal> + in a FPM pool configuration. Previously, the change was silently ignored. + </simpara> </listitem> </varlistentry> <varlistentry xml:id="ini.opcache.interned-strings-buffer"> @@ -1078,6 +1089,32 @@ function getA() { return A; } </caution> </listitem> </varlistentry> + <varlistentry xml:id="ini.opcache.file-cache-read-only"> + <term> + <parameter>opcache.file_cache_read_only</parameter> + <type>bool</type> + </term> + <listitem> + <simpara> + When enabled, allows using a read-only + <link linkend="ini.opcache.file-cache">opcache.file_cache</link> directory. + This is intended for use with read-only file systems such as read-only Docker + containers. Best used in combination with + <literal>opcache.validate_timestamps=0</literal>, + <literal>opcache.enable_file_override=1</literal>, and + <literal>opcache.file_cache_consistency_checks=0</literal>. + </simpara> + <note> + <simpara> + A cache generated with a different build of PHP, a different file path, + or different settings (including which extensions are loaded) may be ignored. + </simpara> + </note> + <simpara> + Available as of PHP 8.5.0. + </simpara> + </listitem> + </varlistentry> <varlistentry xml:id="ini.opcache.validate-permission"> <term> <parameter>opcache.validate_permission</parameter>