[DOC-CVS] [doc-en] master: Update strpos docs with error handling details when offset exceeds length (#4959)

Author: Kevin Boyd (beryllium)
Committer: GitHub (web-flow)
Pusher: TimWolla
Date: 2025-10-28T23:22:11+01:00

Commit: https://github.com/php/doc-en/commit/4b72b23513caa3a8bc520d459a0417defc7b3880
Raw diff: https://github.com/php/doc-en/commit/4b72b23513caa3a8bc520d459a0417defc7b3880.diff

Update strpos docs with error handling details when offset exceeds length (#4959)

* Update strpos.xml with error handling details

Added error handling information for offset parameter, after observing this un/underdocumented fatal in production.

Note: Using the github web editor, I am not sure if I can pull a second file into this PR, so I may submit a second PR to handle `stripos`.

* Document error for offset exceeding haystack length

Added error handling information for offset parameter.

* Document error for exceeding offset length

Added error handling information for offset parameter.

* Document error for offset exceeding haystack length

Added error handling information for offset parameter.

* Apply suggestions from code review

Co-authored-by: Tim Düsterhus <[email protected]>

* Apply review suggestions

* Remove csprng-specific html entity

* Add invalid offset ValueError information to strrpos-related methods

* Fix whitespace for strprpos error message info

---------

Co-authored-by: Tim Düsterhus <[email protected]>

Changed paths:
  M  reference/mbstring/functions/mb-stripos.xml
  M  reference/mbstring/functions/mb-strpos.xml
  M  reference/mbstring/functions/mb-strripos.xml
  M  reference/mbstring/functions/mb-strrpos.xml
  M  reference/strings/functions/stripos.xml
  M  reference/strings/functions/strpos.xml
  M  reference/strings/functions/strripos.xml
  M  reference/strings/functions/strrpos.xml


Diff:

diff --git a/reference/mbstring/functions/mb-stripos.xml b/reference/mbstring/functions/mb-stripos.xml
index 6cae80fb140a..192ea0a092e6 100644
--- a/reference/mbstring/functions/mb-stripos.xml
+++ b/reference/mbstring/functions/mb-stripos.xml
@@ -76,6 +76,19 @@
   </para>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <itemizedlist>
+   <listitem>
+    <simpara>
+     If <parameter>offset</parameter> is greater than the length of
+     <parameter>haystack</parameter>, a
+     <classname>ValueError</classname> will be thrown.
+    </simpara>
+   </listitem>
+  </itemizedlist>
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>
diff --git a/reference/mbstring/functions/mb-strpos.xml b/reference/mbstring/functions/mb-strpos.xml
index 444650d64329..b7ec05bd9056 100644
--- a/reference/mbstring/functions/mb-strpos.xml
+++ b/reference/mbstring/functions/mb-strpos.xml
@@ -77,6 +77,19 @@
   </para>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <itemizedlist>
+   <listitem>
+    <simpara>
+     If <parameter>offset</parameter> is greater than the length of
+     <parameter>haystack</parameter>, a
+     <classname>ValueError</classname> will be thrown.
+    </simpara>
+   </listitem>
+  </itemizedlist>
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>
diff --git a/reference/mbstring/functions/mb-strripos.xml b/reference/mbstring/functions/mb-strripos.xml
index bc4d24e0804d..2f4ae89dc2c2 100644
--- a/reference/mbstring/functions/mb-strripos.xml
+++ b/reference/mbstring/functions/mb-strripos.xml
@@ -78,14 +78,18 @@
   </para>
  </refsect1>
 
- <!-- Use when ERRORS exist
  <refsect1 role="errors">
   &reftitle.errors;
-  <para>
-   When does this function throw E_* level errors, or exceptions?
-  </para>
+  <itemizedlist>
+   <listitem>
+    <simpara>
+     If <parameter>offset</parameter> is greater than the length of
+     <parameter>haystack</parameter>, a
+     <classname>ValueError</classname> will be thrown.
+    </simpara>
+   </listitem>
+  </itemizedlist>
  </refsect1>
- -->
 
  <refsect1 role="changelog">
   &reftitle.changelog;
diff --git a/reference/mbstring/functions/mb-strrpos.xml b/reference/mbstring/functions/mb-strrpos.xml
index cc7fee43fec5..656a4d7b0601 100644
--- a/reference/mbstring/functions/mb-strrpos.xml
+++ b/reference/mbstring/functions/mb-strrpos.xml
@@ -76,6 +76,19 @@
   </para>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <itemizedlist>
+  <listitem>
+   <simpara>
+    If <parameter>offset</parameter> is greater than the length of
+    <parameter>haystack</parameter>, a
+    <classname>ValueError</classname> will be thrown.
+   </simpara>
+  </listitem>
+ </itemizedlist>
+</refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>
diff --git a/reference/strings/functions/stripos.xml b/reference/strings/functions/stripos.xml
index e30d830b6e86..65890b9a08ed 100644
--- a/reference/strings/functions/stripos.xml
+++ b/reference/strings/functions/stripos.xml
@@ -72,6 +72,19 @@
   &return.falseproblem;
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <itemizedlist>
+   <listitem>
+    <simpara>
+     If <parameter>offset</parameter> is greater than the length of
+     <parameter>haystack</parameter>, a
+     <classname>ValueError</classname> will be thrown.
+    </simpara>
+   </listitem>
+  </itemizedlist>
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>
diff --git a/reference/strings/functions/strpos.xml b/reference/strings/functions/strpos.xml
index a8b1aeed6aef..d788148cfd9e 100644
--- a/reference/strings/functions/strpos.xml
+++ b/reference/strings/functions/strpos.xml
@@ -68,6 +68,19 @@
   &return.falseproblem;
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <itemizedlist>
+   <listitem>
+    <simpara>
+     If <parameter>offset</parameter> is greater than the length of
+     <parameter>haystack</parameter>, a
+     <classname>ValueError</classname> will be thrown.
+    </simpara>
+   </listitem>
+  </itemizedlist>
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>
diff --git a/reference/strings/functions/strripos.xml b/reference/strings/functions/strripos.xml
index 9703513145f3..3b069b67eb14 100644
--- a/reference/strings/functions/strripos.xml
+++ b/reference/strings/functions/strripos.xml
@@ -90,6 +90,19 @@
   &return.falseproblem;
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <itemizedlist>
+   <listitem>
+    <simpara>
+     If <parameter>offset</parameter> is greater than the length of
+     <parameter>haystack</parameter>, a
+     <classname>ValueError</classname> will be thrown.
+    </simpara>
+   </listitem>
+  </itemizedlist>
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>
diff --git a/reference/strings/functions/strrpos.xml b/reference/strings/functions/strrpos.xml
index b2b022aa9986..2ec4dba9a261 100644
--- a/reference/strings/functions/strrpos.xml
+++ b/reference/strings/functions/strrpos.xml
@@ -86,6 +86,19 @@
   &return.falseproblem;
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <itemizedlist>
+   <listitem>
+    <simpara>
+     If <parameter>offset</parameter> is greater than the length of
+     <parameter>haystack</parameter>, a
+     <classname>ValueError</classname> will be thrown.
+    </simpara>
+   </listitem>
+  </itemizedlist>
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>