Improve documentation of output control constants (#3039)

Co-authored-by: haszi <[email protected]>
php · Dec 27, 2023 · 2ca114b · 2ca114b
1 parent cb25637
commit 2ca114b
Showing 1 changed file with 64 additions and 3 deletions.
diff --git a/reference/outcontrol/constants.xml b/reference/outcontrol/constants.xml
@@ -4,6 +4,10 @@
  &reftitle.constants;
  &extension.constants.core;
  <variablelist>
+  <title>Status flags passed to output handler</title>
+  <para>
+   The following flags are passed to the second (<parameter>phase</parameter>) parameter of the output handler set by <function>ob_start</function> as part of a bitmask:
+  </para>
   <varlistentry xml:id="constant.php-output-handler-start">
    <term>
     <constant>PHP_OUTPUT_HANDLER_START</constant>
@@ -90,6 +94,12 @@
     </para>
    </listitem>
   </varlistentry>
+ </variablelist>
+ <variablelist>
+  <title>Output buffer control flags</title>
+  <para>
+   The following flags can be passed to the third (<parameter>flags</parameter>) parameter of the output handler set by <function>ob_start</function> as a bitmask:
+  </para>
   <varlistentry xml:id="constant.php-output-handler-cleanable">
    <term>
     <constant>PHP_OUTPUT_HANDLER_CLEANABLE</constant>
@@ -98,7 +108,10 @@
    <listitem>
     <para>
      Controls whether an output buffer created by
-     <function>ob_start</function> can be cleaned.
+     <function>ob_start</function> can be cleaned
+     by <function>ob_clean</function>.
+     This flag does not control the behaviour of
+     <function>ob_end_clean</function> or <function>ob_get_clean</function>.
     </para>
    </listitem>
   </varlistentry>
@@ -110,7 +123,10 @@
    <listitem>
     <para>
      Controls whether an output buffer created by
-     <function>ob_start</function> can be flushed.
+     <function>ob_start</function> can be flushed
+     by <function>ob_flush</function>.
+     This flag does not control the behaviour of
+     <function>ob_end_flush</function> or <function>ob_get_flush</function>.
     </para>
    </listitem>
   </varlistentry>
@@ -122,7 +138,9 @@
    <listitem>
     <para>
      Controls whether an output buffer created by
-     <function>ob_start</function> can be removed before the end of the script.
+     <function>ob_start</function> can be removed before the end of the script
+     or when calling <function>ob_end_clean</function>, <function>ob_end_flush</function>,
+     <function>ob_get_clean</function> or <function>ob_get_flush</function>.
     </para>
    </listitem>
   </varlistentry>
@@ -141,6 +159,49 @@
    </listitem>
   </varlistentry>
  </variablelist>
+ <variablelist>
+  <title>Output handler status flags</title>
+  <para>
+   The following flags are part of the <literal>flags</literal> bitmask
+   returned by <function>ob_get_status</function>:
+  </para>
+  <varlistentry xml:id="constant.php-output-handler-started">
+   <term>
+    <constant>PHP_OUTPUT_HANDLER_STARTED</constant>
+    (<type>int</type>)
+   </term>
+   <listitem>
+    <para>
+     Indicates that the output handler was called.
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry xml:id="constant.php-output-handler-disabled">
+   <term>
+    <constant>PHP_OUTPUT_HANDLER_DISABLED</constant>
+    (<type>int</type>)
+   </term>
+   <listitem>
+    <para>
+     Indicates that the output handler is disabled.
+     This flag is set when the output handler returns &false;
+     or fails while processing the buffer,
+     or it was set prior to calling the output handler.
+    </para>
+   </listitem>
+  </varlistentry>
+  <varlistentry xml:id="constant.php-output-handler-processed">
+   <term>
+    <constant>PHP_OUTPUT_HANDLER_PROCESSED</constant>
+    (<type>int</type>)
+   </term>
+   <listitem>
+    <para>
+     Indicates that the output handler successfully processed the buffer.
+    </para>
+   </listitem>
+  </varlistentry>
+ </variablelist>
 </appendix>
 <!-- Keep this comment at the end of the file
 Local variables: