Skip to content

Filter: Document FILTER_CALLBACK #4143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 24, 2024
Merged

Filter: Document FILTER_CALLBACK #4143

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e88eaa0
Filter: Document FILTER_CALLBACK
Girgias Nov 24, 2024
0785390
Apply suggestions from code review
Girgias Nov 24, 2024
6ca1d56
Add methodsnyopsis
Girgias Nov 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 67 additions & 3 deletions reference/filter/constants.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
31 changes: 0 additions & 31 deletions reference/filter/filters.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down