From 412745300897ec2f8d1f5345463e0e82734e0cfc Mon Sep 17 00:00:00 2001
From: Jordi Kroon <jkroon@onyourmarks.agency>
Date: Mon, 22 Dec 2025 00:13:56 +0100
Subject: [PATCH 1/4] docs: add OPCache file cache and JIT blacklist functions

Add documentation for two new OPCache functions:
- opcache_is_script_cached_in_file_cache: checks if a script is cached in OPCache file cache
- opcache_jit_blacklist: blacklists a function from being JIT compiled

Update opcache_is_script_cached documentation to clarify it checks in-memory cache and cross-reference the new file cache function.
---
 ...opcache-is-script-cached-in-file-cache.xml | 74 ++++++++++++++++
 .../functions/opcache-is-script-cached.xml    |  8 +-
 .../functions/opcache-jit-blacklist.xml       | 84 +++++++++++++++++++
 3 files changed, 163 insertions(+), 3 deletions(-)
 create mode 100644 reference/opcache/functions/opcache-is-script-cached-in-file-cache.xml
 create mode 100644 reference/opcache/functions/opcache-jit-blacklist.xml

diff --git a/reference/opcache/functions/opcache-is-script-cached-in-file-cache.xml b/reference/opcache/functions/opcache-is-script-cached-in-file-cache.xml
new file mode 100644
index 000000000000..f94c4ea929d4
--- /dev/null
+++ b/reference/opcache/functions/opcache-is-script-cached-in-file-cache.xml
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xml:id="function.opcache-is-script-cached-in-file-cache" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>opcache_is_script_cached_in_file_cache</refname>
+  <refpurpose>Tells whether a script is cached in OPCache file cache</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>bool</type><methodname>opcache_is_script_cached_in_file_cache</methodname>
+   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+   This function checks if a PHP script has been cached in OPCache. This can be
+   used to more easily detect the "warming" of the cache for a particular script.
+   This function only checks file cache cache, not in-memory cache. In order to
+   check in-memory cache, use <function>opcache_is_script_cached</function>.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>filename</parameter></term>
+    <listitem>
+     <para>
+      The path to the PHP script to be checked.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   Returns &true; if <parameter>filename</parameter> is cached in OPCache,
+   &false; otherwise.
+  </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>opcache_compile_file</function></member>
+    <member><function>opcache_is_script_cached</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+</refentry>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->
diff --git a/reference/opcache/functions/opcache-is-script-cached.xml b/reference/opcache/functions/opcache-is-script-cached.xml
index 03df796c2128..d18be80ee0e4 100644
--- a/reference/opcache/functions/opcache-is-script-cached.xml
+++ b/reference/opcache/functions/opcache-is-script-cached.xml
@@ -13,9 +13,10 @@
    <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   </methodsynopsis>
   <para>
-   This function checks if a PHP script has been cached in OPCache. This can be
+   This function checks if a PHP script has been cached in OPCache in-memory cache. This can be
    used to more easily detect the "warming" of the cache for a particular script.
-   This function only checks in-memory cache, not file cache.
+   This function only checks in-memory cache, not file cache. In order to
+   check file cache, use <function>opcache_is_script_cached_in_file_cache</function>.
   </para>
  </refsect1>
 
@@ -36,7 +37,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   Returns &true; if <parameter>filename</parameter> is cached in OPCache,
+   Returns &true; if <parameter>filename</parameter> is cached in OPCache in-memory cache,
    &false; otherwise.
   </para>
  </refsect1>
@@ -46,6 +47,7 @@
   <para>
    <simplelist>
     <member><function>opcache_compile_file</function></member>
+    <member><function>opcache_is_script_cached_in_file_cache</function></member>
    </simplelist>
   </para>
  </refsect1>
diff --git a/reference/opcache/functions/opcache-jit-blacklist.xml b/reference/opcache/functions/opcache-jit-blacklist.xml
new file mode 100644
index 000000000000..61f7fb5fb56d
--- /dev/null
+++ b/reference/opcache/functions/opcache-jit-blacklist.xml
@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision$ -->
+<refentry xml:id="function.opcache-jit-blacklist" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>opcache_jit_blacklist</refname>
+  <refpurpose>Blacklists a function from being JIT compiled</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type>void</type><methodname>opcache_jit_blacklist</methodname>
+   <methodparam><type>Closure</type><parameter>closure</parameter></methodparam>
+  </methodsynopsis>
+  <para>
+    This function blacklists a particular function from being JIT compiled.
+    The function is specified using a Closure.
+  </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <variablelist>
+   <varlistentry>
+    <term><parameter>closure</parameter></term>
+    <listitem>
+     <para>
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>opcache_jit_blacklist</function> basic example</title>
+   <programlisting role="php">
+    <![CDATA[
+<?php
+function foo() {
+	$x = 1;
+	$x += 0;
+	++$x;
+	var_dump($x);
+}
+opcache_jit_blacklist(foo(...));
+foo();
+?>
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
+ 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>opcache_invalidate</function></member>
+    <member><function>opcache_reset</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+</refentry>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->

From 17839f1ca5b92b80c527499b47e248569072784a Mon Sep 17 00:00:00 2001
From: Jordi Kroon <jkroon@onyourmarks.agency>
Date: Mon, 22 Dec 2025 00:33:59 +0100
Subject: [PATCH 2/4] docs: add opcache functions introduced in PHP 8.4 and 8.5

Add version information for two new opcache functions:
- opcache_is_script_cached_in_file_cache (PHP 8.5.0+)
- opcache_jit_blacklist (PHP 8.4.0+)
---
 reference/opcache/versions.xml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/reference/opcache/versions.xml b/reference/opcache/versions.xml
index 9a5363ab1342..36aa3ea44739 100644
--- a/reference/opcache/versions.xml
+++ b/reference/opcache/versions.xml
@@ -9,6 +9,8 @@
  <function name="opcache_get_status" from="PHP 5 &gt;= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache &gt; 7.0.2"/>
  <function name="opcache_invalidate" from="PHP 5 &gt;= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache &gt;= 7.0.0"/>
  <function name="opcache_is_script_cached" from="PHP 5 &gt;= 5.5.11, PHP 7, PHP 8, PECL ZendOpcache &gt;= 7.0.4"/>
+ <function name="opcache_is_script_cached_in_file_cache" from="PHP 8 &gt;= 8.5.0"/>
+ <function name="opcache_jit_blacklist" from="PHP 8 &gt;= 8.4.0"/>
  <function name="opcache_reset" from="PHP 5 &gt;= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache &gt;= 7.0.0"/>
 </versions>
 <!-- Keep this comment at the end of the file

From 96afd5cdd928bbeb867b03b16b1eacb7f21f89e8 Mon Sep 17 00:00:00 2001
From: Jordi Kroon <jkroon@onyourmarks.agency>
Date: Sat, 27 Dec 2025 00:53:38 +0100
Subject: [PATCH 3/4] docs: improve opcache_jit_blacklist documentation
 formatting

- Reformat XML elements for better readability with consistent indentation
- Add missing returnvalues section with &return.void; entity
- Improve title element formatting for the basic example
- Standardize spacing in seealso section
- Fix trailing whitespace and comment indentation
---
 .../functions/opcache-jit-blacklist.xml       | 78 ++++++++++++-------
 1 file changed, 49 insertions(+), 29 deletions(-)

diff --git a/reference/opcache/functions/opcache-jit-blacklist.xml b/reference/opcache/functions/opcache-jit-blacklist.xml
index 61f7fb5fb56d..67cad4002b45 100644
--- a/reference/opcache/functions/opcache-jit-blacklist.xml
+++ b/reference/opcache/functions/opcache-jit-blacklist.xml
@@ -9,12 +9,16 @@
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
-   <type>void</type><methodname>opcache_jit_blacklist</methodname>
-   <methodparam><type>Closure</type><parameter>closure</parameter></methodparam>
+   <type>void</type>
+   <methodname>opcache_jit_blacklist</methodname>
+   <methodparam>
+    <type>Closure</type>
+    <parameter>closure</parameter>
+   </methodparam>
   </methodsynopsis>
   <para>
-    This function blacklists a particular function from being JIT compiled.
-    The function is specified using a Closure.
+   This function blacklists a particular function from being JIT compiled.
+   The function is specified using a Closure.
   </para>
  </refsect1>
 
@@ -22,7 +26,9 @@
   &reftitle.parameters;
   <variablelist>
    <varlistentry>
-    <term><parameter>closure</parameter></term>
+    <term>
+     <parameter>closure</parameter>
+    </term>
     <listitem>
      <para>
      </para>
@@ -31,10 +37,20 @@
   </variablelist>
  </refsect1>
 
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <para>
+   &return.void;
+  </para>
+ </refsect1>
+ 
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title><function>opcache_jit_blacklist</function> basic example</title>
+   <title>
+    <function>opcache_jit_blacklist</function>
+    basic example
+   </title>
    <programlisting role="php">
     <![CDATA[
 <?php
@@ -51,34 +67,38 @@ foo();
    </programlisting>
   </example>
  </refsect1>
- 
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><function>opcache_invalidate</function></member>
-    <member><function>opcache_reset</function></member>
+    <member>
+     <function>opcache_invalidate</function>
+    </member>
+    <member>
+     <function>opcache_reset</function>
+    </member>
    </simplelist>
   </para>
  </refsect1>
 </refentry>
-<!-- Keep this comment at the end of the file
-Local variables:
-mode: sgml
-sgml-omittag:t
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-indent-tabs-mode:nil
-sgml-parent-document:nil
-sgml-default-dtd-file:"~/.phpdoc/manual.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:nil
-sgml-local-ecat-files:nil
-End:
-vim600: syn=xml fen fdm=syntax fdl=2 si
-vim: et tw=78 syn=sgml
-vi: ts=1 sw=1
--->
+ <!-- Keep this comment at the end of the file
+ Local variables:
+ mode: sgml
+ sgml-omittag:t
+ sgml-shorttag:t
+ sgml-minimize-attributes:nil
+ sgml-always-quote-attributes:t
+ sgml-indent-step:1
+ sgml-indent-data:t
+ indent-tabs-mode:nil
+ sgml-parent-document:nil
+ sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+ sgml-exposed-tags:nil
+ sgml-local-catalogs:nil
+ sgml-local-ecat-files:nil
+ End:
+ vim600: syn=xml fen fdm=syntax fdl=2 si
+ vim: et tw=78 syn=sgml
+ vi: ts=1 sw=1
+ -->

From f224e0b2b94df7dc41a2a30e24471589100553f9 Mon Sep 17 00:00:00 2001
From: Jordi Kroon <jkroon@onyourmarks.agency>
Date: Sat, 27 Dec 2025 00:58:56 +0100
Subject: [PATCH 4/4] style: remove trailing whitespace in
 opcache-jit-blacklist.xml

---
 reference/opcache/functions/opcache-jit-blacklist.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/opcache/functions/opcache-jit-blacklist.xml b/reference/opcache/functions/opcache-jit-blacklist.xml
index 67cad4002b45..3a39223fc8cb 100644
--- a/reference/opcache/functions/opcache-jit-blacklist.xml
+++ b/reference/opcache/functions/opcache-jit-blacklist.xml
@@ -43,7 +43,7 @@
    &return.void;
   </para>
  </refsect1>
- 
+
  <refsect1 role="examples">
   &reftitle.examples;
   <example>