Add examples for mb_scrub() (#5811)

* Add examples for mb_scrub()

The page had no example, which made it hard to see that the replacement
happens in the string itself: terminals, browsers and fonts render an
ill-formed byte sequence with a replacement character of their own, so
visual output alone is misleading. Both examples use bin2hex() or
var_dump() so the reader sees the bytes rather than the rendering.

The first example also shows that the result depends on the substitute
character: mbstring.substitute_character defaults to "?" (0x3F), so the
scrubbed string is 41 3f 42, and 41 ef bf bd 42 only after calling
mb_substitute_character(0xFFFD).

The second example shows the practical use: a PCRE pattern with the u
modifier fails on the raw input and succeeds once it has been scrubbed.

A see also section is added, since the page had none and the substitute
character is a prerequisite for reading the first example.

Outputs verified on PHP 8.1, 8.4 and 8.5.

Fixes: #5562

* Unwrap examples and see also list from para

Author: lacatoire

reference/mbstring/functions/mb-scrub.xml

@@ -71,6 +71,84 @@
   </informaltable>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title>Byte-level replacement performed by <function>mb_scrub</function></title>
+   <simpara>
+    <function>bin2hex</function> is used here because terminals, browsers and
+    fonts may render an ill-formed byte sequence with a replacement character
+    of their own, which hides what the string actually contains.
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+// The byte 0xFF cannot appear in a valid UTF-8 string.
+$input = "A\xFFB";
+echo bin2hex($input), "\n";
+
+// The default substitute character is "?" (0x3F).
+echo bin2hex(mb_scrub($input, 'UTF-8')), "\n";
+
+// U+FFFD REPLACEMENT CHARACTER is encoded as EF BF BD in UTF-8.
+mb_substitute_character(0xFFFD);
+echo bin2hex(mb_scrub($input, 'UTF-8')), "\n";
+
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+41ff42
+413f42
+41efbfbd42
+]]>
+   </screen>
+  </example>
+  <example>
+   <title>Using <function>mb_scrub</function> before UTF-8 aware processing</title>
+   <simpara>
+    PCRE patterns using the <literal>u</literal> modifier reject subjects that
+    are not well-formed UTF-8. Scrubbing the input first makes it acceptable.
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$input = "A\xFFB";
+
+var_dump(preg_match_all('/./us', $input));
+echo preg_last_error_msg(), "\n";
+
+$clean = mb_scrub($input, 'UTF-8');
+
+var_dump(preg_match_all('/./us', $clean));
+
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+bool(false)
+Malformed UTF-8 characters, possibly incorrectly encoded
+int(3)
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <simplelist>
+   <member><function>mb_substitute_character</function></member>
+   <member><function>mb_check_encoding</function></member>
+   <member><function>mb_convert_encoding</function></member>
+  </simplelist>
+ </refsect1>
+
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables: