Filter: Document FILTER_CALLBACK (#4143)

Co-authored-by: Kamil Tekiela <[email protected]>

Author: Girgias

reference/filter/constants.xml

@@ -1039,11 +1039,75 @@
     (<type>int</type>)
    </term>
    <listitem>
-    <!-- TODO: Document how to use this filter, see user notes on manual page:
-    https://www.php.net/manual/en/filter.filters.misc.php -->
     <simpara>
-     ID of "callback" filter.
+     This filter delegates the filtering to a user defined function.
+     The <type>callable</type> is passed via the
+     <parameter>options</parameter> parameter as the value associated to
+     the <literal>'options'</literal> key.
     </simpara>
+    <para>
+     The callback should have the following signature:
+     <methodsynopsis>
+      <type>mixed</type><methodname><replaceable>callback</replaceable></methodname>
+      <methodparam><type>string</type><parameter>value</parameter></methodparam>
+     </methodsynopsis>
+     <variablelist role="function_parameters">
+      <varlistentry>
+       <term><parameter>value</parameter></term>
+       <listitem>
+        <simpara>
+         The value that is being filtered.
+        </simpara>
+       </listitem>
+      </varlistentry>
+     </variablelist>
+    </para>
+    <note>
+     <simpara>
+      The value returned by the callback will be the value returned by
+      the invoked filter function.
+     </simpara>
+    </note>
+    <example>
+     <title>
+      Example of using <constant>FILTER_CALLBACK</constant> to validate
+      a login name
+     </title>
+     <programlisting role="php">
+<![CDATA[
+<?php
+function validate_login($value): ?string
+{
+    if (strlen($value) >= 5 && ctype_alnum($value)) {
+        return $value;
+    }
+    return null;
+}
+
+$login = "val1dL0gin";
+$filtered_login = filter_var($login, FILTER_CALLBACK, ['options' => 'validate_login']);
+var_dump($filtered_login);
+
+$login = "f&ke login";
+$filtered_login = filter_var($login, FILTER_CALLBACK, ['options' => 'validate_login']);
+var_dump($filtered_login);
+?>
+]]>
+     </programlisting>
+     &example.outputs;
+     <screen>
+<![CDATA[
+string(10) "val1dL0gin"
+NULL
+]]>
+     </screen>
+    </example>
+    <warning>
+     <simpara>
+      This filter cannot be used with any other filter flags, e.g.
+      <constant>FILTER_NULL_ON_FAILURE</constant>.
+     </simpara>
+    </warning>
    </listitem>
   </varlistentry>
  </variablelist>

reference/filter/filters.xml

@@ -129,37 +129,6 @@
  </section>
  <!--}}}-->
 
- <!-- Other filters: {{{-->
- <section xml:id="filter.filters.misc">
-  <title>Other filters</title>
-   <para>
-    <table>
-     <title>List of miscellaneous filters</title>
-     <tgroup cols="5">
-      <thead>
-       <row>
-        <entry>ID</entry>
-        <entry>Name</entry>
-        <entry>Options</entry>
-        <entry>Flags</entry>
-        <entry>Description</entry>
-       </row>
-      </thead>
-      <tbody>
-       <row>
-        <entry><constant>FILTER_CALLBACK</constant></entry>
-        <entry>"callback"</entry>
-        <entry><type>callable</type> function or method</entry>
-        <entry>All flags are ignored</entry>
-        <entry>Call user-defined function to filter data.</entry>
-       </row>
-      </tbody>
-     </tgroup>
-    </table>
-   </para>
- </section>
- <!--}}}-->
-
  <!-- Filter flags: {{{-->
  <section xml:id="filter.filters.flags">
   <title>Filter flags</title>