add details about optimizer passes

reference/opcache/ini.xml

@@ -592,10 +592,155 @@
     <listitem>
      <para>
       A bitmask that controls which optimisation passes are executed.
-      The default is to apply all safe optimizations.
-      Changing the default is mostly useful for debugging/developing the optimizer
-      (see also <link linkend="ini.opcache.opt_debug_level">opcache.opt_debug_level</link>).
-     </para>
+      The default value is <literal>0x7FFEBFFF</literal>, which enables all
+      safe optimizations. Disabling optimizations or enabling unsafe optimizations
+      is mostly useful for debugging/developing the optimizer.
+     </para>
+     <para>
+      Each bit in the bitmask enables a specific optimization pass:
+     </para>
+     <table>
+      <title>Optimization Pass Bitmask</title>
+      <tgroup cols="6">
+       <thead>
+        <row>
+         <entry>Bit</entry>
+         <entry>Pass Name</entry>
+         <entry>Description</entry>
+         <entry>Default</entry>
+        </row>
+       </thead>
+       <tbody>
+        <row>
+         <entry>0</entry>
+         <entry>PASS_1</entry>
+         <entry>Simple local optimizations: constant substitution, expression evaluation, conditional JMP optimization</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>1</entry>
+         <entry>PASS_2</entry>
+         <entry>Reserved - unused since PHP 7.4 - as functionality got merged into PASS_1</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>2</entry>
+         <entry>PASS_3</entry>
+         <entry>Jump optimization: optimizes series of JMPs</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>3</entry>
+         <entry>PASS_4</entry>
+         <entry>Function call optimization: INIT_FCALL_BY_NAME to DO_FCALL conversion</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>4</entry>
+         <entry>PASS_5</entry>
+         <entry>CFG optimization: Control Flow Graph based optimization</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>5</entry>
+         <entry>PASS_6</entry>
+         <entry>DFA optimization: Data Flow Analysis based optimization</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>6</entry>
+         <entry>PASS_7</entry>
+         <entry>Call graph optimization: whole-script optimization using call graph</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>7</entry>
+         <entry>PASS_8</entry>
+         <entry>SCCP: Sparse Conditional Constant Propagation</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>8</entry>
+         <entry>PASS_9</entry>
+         <entry>TMP VAR optimization: optimize temporary variable usage</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>9</entry>
+         <entry>PASS_10</entry>
+         <entry>NOP removal: remove no-operation instructions</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>10</entry>
+         <entry>PASS_11</entry>
+         <entry>Merge equal constants: compact literals table</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>11</entry>
+         <entry>PASS_12</entry>
+         <entry>Adjust stack size: optimize function call stack size</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>12</entry>
+         <entry>PASS_13</entry>
+         <entry>Remove unused variables: remove compiled variables that are never used</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>13</entry>
+         <entry>PASS_14</entry>
+         <entry>DCE: Dead Code Elimination</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>14</entry>
+         <entry>PASS_15</entry>
+         <entry>Collect constants: aggressive constant collection (unsafe)</entry>
+         <entry><emphasis>Off</emphasis></entry>
+        </row>
+        <row>
+         <entry>15</entry>
+         <entry>PASS_16</entry>
+         <entry>Inline functions: function inlining optimization</entry>
+         <entry>On</entry>
+        </row>
+        <row>
+         <entry>16</entry>
+         <entry>(Flag)</entry>
+         <entry>Ignore overloading: assume no operator overloading (unsafe). Not a pass; modifies optimizer behavior</entry>
+         <entry><emphasis>Off</emphasis></entry>
+        </row>
+       </tbody>
+      </tgroup>
+     </table>
+     <note>
+      <title>Safe vs Unsafe Optimizations</title>
+      <para>
+       <emphasis>Safe optimizations</emphasis> (enabled by default) preserve the exact
+       behavior of PHP code while improving performance. They include dead code elimination,
+       constant folding, and jump optimization.
+      </para>
+      <para>
+       <emphasis>Unsafe optimizations</emphasis> (disabled by default) may alter behavior
+       in edge cases:
+      </para>
+      <itemizedlist>
+       <listitem>
+        <para>
+         <emphasis>Bit 14</emphasis>: Aggressive constant collection may not preserve
+         exact behavior in all edge cases
+        </para>
+       </listitem>
+       <listitem>
+        <para>
+         <emphasis>Bit 16</emphasis>: Ignoring operator overloading
+        </para>
+       </listitem>
+      </itemizedlist>
+     </note>
     </listitem>
    </varlistentry>
    <varlistentry xml:id="ini.opcache.inherited-hack">