[doc-en] master: opcache: document how opcache.restrict_api matches the script path (#6067)
| From: | Asish Kumar via GitHub | Date: | Thu, 12 Nov 2026 15:21:21 +0000 |
| Subject: | [doc-en] master: opcache: document how opcache.restrict_api matches the script path (#6067) | ||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-23945@lists.php.net to get a copy of this message | ||
Author: Asish Kumar (officialasishkumar)
Committer: GitHub (web-flow)
Pusher: lacatoire
Date: 2026-11-12T16:21:17+01:00
Commit: https://github.com/php/doc-en/commit/8cdccd62091924e8fdec3424c748c3a34f279ceb
Raw diff: https://github.com/php/doc-en/commit/8cdccd62091924e8fdec3424c748c3a34f279ceb.diff
opcache: document how opcache.restrict_api matches the script path (#6067)
* opcache: document how opcache.restrict_api matches the script path
validate_api_restriction() compares opcache.restrict_api with
SG(request_info).path_translated using memcmp(). That has a few
consequences the ini entry did not mention, and that led to #1639, where
C:\server worked on the CLI but not through Apache on Windows:
- The path checked is the one of the main script, as reported by the
SAPI, not the one of the file calling the function. Files included by
an allowed script may call the API, files in the allowed directory
included by another script may not.
- The CLI resolves symbolic links in the script path first.
- It is a plain, case-sensitive prefix match without normalization, so
/var/www/admin also allows /var/www/administrator, and the value must
use the directory separators of the path the SAPI reports. With
apache2handler on Windows that path uses forward slashes.
Also list the functions that are restricted, and that they raise an
E_WARNING and return false. opcache_compile_file() and
opcache_jit_blacklist() are not restricted.
Checked against ext/opcache/zend_accelerator_module.c and
sapi/cli/php_cli.c, and on PHP 8.4 with the CLI.
Fixes #1639
* opcache: clarify restrict_api wording and the 8.5.0 availability note
Changed paths:
M reference/opcache/ini.xml
Diff:
diff --git a/reference/opcache/ini.xml b/reference/opcache/ini.xml
index b4965c0c0978..72f88f8ce332 100644
--- a/reference/opcache/ini.xml
+++ b/reference/opcache/ini.xml
@@ -967,9 +967,36 @@ function getA() { return A; }
</term>
<listitem>
<simpara>
- Allows calling OPcache API functions only from PHP scripts which path
- is started from specified string. The default <literal>""</literal>
+ Allows calling OPcache API functions only from PHP scripts whose path
+ starts with the specified string. The default <literal>""</literal>
means no restriction.
+ When the restriction applies, <function>opcache_get_status</function>,
+ <function>opcache_get_configuration</function>,
+ <function>opcache_reset</function>,
<function>opcache_invalidate</function>,
+ <function>opcache_is_script_cached</function> and
+ <function>opcache_is_script_cached_in_file_cache</function> (as of PHP 8.5.0)
+ raise an <constant>E_WARNING</constant> and return &false;.
+ </simpara>
+ <simpara>
+ The path that is checked is the one of the main script, that is the
+ script requested from the web server or passed to the CLI, as reported by
+ the SAPI. The path of the file the function is called from does not
+ matter: files included by an allowed script may call the API, whereas
+ files in the allowed directory may not if they are included by a script
+ outside of it. The CLI SAPI resolves symbolic links in the path of the
+ script before it is checked.
+ </simpara>
+ <simpara>
+ The comparison is a plain, case-sensitive prefix match, without any
+ normalization of the paths. As a consequence, a value of
+ <literal>/var/www/admin</literal> also allows scripts in
+ <literal>/var/www/administrator</literal>; end the value with a directory
+ separator to match only that directory and its subdirectories. The value
+ must also use the same directory separators as the path reported by the SAPI: with the
+ apache2handler SAPI on Windows, that path uses forward slashes (for instance
+ <literal>C:/www/admin/status.php</literal>), so
+ <literal>C:/www/admin</literal> has to be used instead of
+ <literal>C:\www\admin</literal>.
</simpara>
</listitem>
</varlistentry>