[DOC-CVS] [doc-en] master: Document FILTER_THROW_ON_FAILURE and the Filter exception classes (PHP 8.5) (#5607)

Author: Louis-Arnaud (lacatoire)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-06-15T20:05:26+02:00

Commit: https://github.com/php/doc-en/commit/3d4ee5f40afbfe44db4f1b13a22a6a38d4b40c7b
Raw diff: https://github.com/php/doc-en/commit/3d4ee5f40afbfe44db4f1b13a22a6a38d4b40c7b.diff

Document FILTER_THROW_ON_FAILURE and the Filter exception classes (PHP 8.5) (#5607)

* Document FILTER_THROW_ON_FAILURE and Filter exception classes (PHP 8.5)

Co-authored-by: Jordi Kroon <[email protected]>

Changed paths:
  A  reference/filter/filter.filterexception.xml
  A  reference/filter/filter.filterfailedexception.xml
  M  reference/filter/book.xml
  M  reference/filter/constants.xml


Diff:

diff --git a/reference/filter/book.xml b/reference/filter/book.xml
index c17d69236fb9..4bb89b2a1eed 100644
--- a/reference/filter/book.xml
+++ b/reference/filter/book.xml
@@ -55,6 +55,9 @@
  &reference.filter.examples;
  &reference.filter.reference;
 
+ &reference.filter.filter.filterexception;
+ &reference.filter.filter.filterfailedexception;
+
 </book>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/filter/constants.xml b/reference/filter/constants.xml
index 97e115b48bb8..7acb610ab102 100644
--- a/reference/filter/constants.xml
+++ b/reference/filter/constants.xml
@@ -156,6 +156,26 @@
     </simpara>
    </listitem>
   </varlistentry>
+  <varlistentry xml:id="constant.filter-throw-on-failure">
+   <term>
+    <constant>FILTER_THROW_ON_FAILURE</constant>
+    (<type>int</type>)
+   </term>
+   <listitem>
+    <simpara>
+     Throws a <exceptionname>Filter\FilterFailedException</exceptionname> when a
+     validation filter fails, instead of returning &false;.
+    </simpara>
+    <simpara>
+     Can be used with any validation
+     <constant>FILTER_VALIDATE_<replaceable>*</replaceable></constant>
+     filter.
+    </simpara>
+    <simpara>
+     Available as of PHP 8.5.0.
+    </simpara>
+   </listitem>
+  </varlistentry>
  </variablelist>
 
  <variablelist xml:id="filter.constants.flags.sanitization">
diff --git a/reference/filter/filter.filterexception.xml b/reference/filter/filter.filterexception.xml
new file mode 100644
index 000000000000..a9f684107376
--- /dev/null
+++ b/reference/filter/filter.filterexception.xml
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="utf-8"?>
+<reference xml:id="class.filter-filterexception" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <title>The Filter\FilterException class</title>
+ <titleabbrev>Filter\FilterException</titleabbrev>
+
+ <partintro>
+  <section xml:id="filter-filterexception.intro">
+   &reftitle.intro;
+   <simpara>
+    The base class for <type>Exception</type>s thrown by the Filter extension.
+   </simpara>
+  </section>
+
+  <section xml:id="filter-filterexception.synopsis">
+   &reftitle.classsynopsis;
+
+   <packagesynopsis>
+    <package>Filter</package>
+
+    <classsynopsis class="class">
+     <ooexception>
+      <exceptionname>FilterException</exceptionname>
+     </ooexception>
+
+     <ooclass>
+      <modifier>extends</modifier>
+      <classname>Exception</classname>
+     </ooclass>
+
+     <classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo>
+     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:partintro/db:section/db:classsynopsis/db:fieldsynopsis[preceding-sibling::db:classsynopsisinfo[1][@role='comment' and text()='&Properties;']]))">
+      <xi:fallback/>
+     </xi:include>
+
+     <classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
+     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='Exception'])">
+      <xi:fallback/>
+     </xi:include>
+     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='Exception'])">
+      <xi:fallback/>
+     </xi:include>
+    </classsynopsis>
+   </packagesynopsis>
+  </section>
+ </partintro>
+</reference>
+<!-- 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/filter/filter.filterfailedexception.xml b/reference/filter/filter.filterfailedexception.xml
new file mode 100644
index 000000000000..09437eacda80
--- /dev/null
+++ b/reference/filter/filter.filterfailedexception.xml
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="utf-8"?>
+<reference xml:id="class.filter-filterfailedexception" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <title>The Filter\FilterFailedException class</title>
+ <titleabbrev>Filter\FilterFailedException</titleabbrev>
+
+ <partintro>
+  <section xml:id="filter-filterfailedexception.intro">
+   &reftitle.intro;
+   <simpara>
+    Thrown when a validation filter fails and the
+    <constant>FILTER_THROW_ON_FAILURE</constant> flag is set.
+   </simpara>
+  </section>
+
+  <section xml:id="filter-filterfailedexception.synopsis">
+   &reftitle.classsynopsis;
+
+   <packagesynopsis>
+    <package>Filter</package>
+
+    <classsynopsis class="class">
+     <ooexception>
+      <exceptionname>FilterFailedException</exceptionname>
+     </ooexception>
+
+     <ooclass>
+      <modifier>extends</modifier>
+      <classname>Filter\FilterException</classname>
+     </ooclass>
+
+     <classsynopsisinfo role="comment">&InheritedProperties;</classsynopsisinfo>
+     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:partintro/db:section/db:classsynopsis/db:fieldsynopsis[preceding-sibling::db:classsynopsisinfo[1][@role='comment' and text()='&Properties;']]))">
+      <xi:fallback/>
+     </xi:include>
+
+     <classsynopsisinfo role="comment">&InheritedMethods;</classsynopsisinfo>
+     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='Exception'])">
+      <xi:fallback/>
+     </xi:include>
+     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.exception')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='Exception'])">
+      <xi:fallback/>
+     </xi:include>
+    </classsynopsis>
+   </packagesynopsis>
+  </section>
+ </partintro>
+</reference>
+<!-- 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
+-->