From 8b0efc4fb8745cde6c3f041e2b3c0c4f7ce84f95 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maur=C3=ADcio=20Meneghini=20Fauth?= <mauricio@mfauth.com.br>
Date: Fri, 18 Sep 2026 16:49:31 -0300
Subject: [PATCH] Add examples to Sodium base64 functions

- sodium_base642bin()
- sodium_bin2base64()
---
 .../sodium/functions/sodium-base642bin.xml    | 75 +++++++++++++++++++
 .../sodium/functions/sodium-bin2base64.xml    | 53 +++++++++++++
 reference/url/functions/base64-decode.xml     |  1 +
 reference/url/functions/base64-encode.xml     |  1 +
 4 files changed, 130 insertions(+)

diff --git a/reference/sodium/functions/sodium-base642bin.xml b/reference/sodium/functions/sodium-base642bin.xml
index 28cd02eef742..f9f3e8075d57 100644
--- a/reference/sodium/functions/sodium-base642bin.xml
+++ b/reference/sodium/functions/sodium-base642bin.xml
@@ -73,6 +73,81 @@
   </simpara>
  </refsect1>
 
+ <refsect1 role="examples"><!-- {{{ -->
+  &reftitle.examples;
+  <example xml:id="sodium-base642bin.example.basic"><!-- {{{ -->
+   <title><function>sodium_base642bin</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$string = 'VGhpcyBpcyBhbiBlbmNvZGVkIHN0cmluZw==';
+echo sodium_base642bin($string, SODIUM_BASE64_VARIANT_ORIGINAL);
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+This is an encoded string
+]]>
+   </screen>
+  </example><!-- }}} -->
+
+  <example xml:id="sodium-base642bin.example.id"><!-- {{{ -->
+   <title>Example of the <parameter>id</parameter> parameter</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+var_dump(sodium_bin2hex(sodium_base642bin('rrZ5j+9OUYT/O1WWr3U0hw==', SODIUM_BASE64_VARIANT_ORIGINAL)));
+var_dump(sodium_bin2hex(sodium_base642bin('rrZ5j+9OUYT/O1WWr3U0hw', SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING)));
+var_dump(sodium_bin2hex(sodium_base642bin('rrZ5j-9OUYT_O1WWr3U0hw==', SODIUM_BASE64_VARIANT_URLSAFE)));
+var_dump(sodium_bin2hex(sodium_base642bin('rrZ5j-9OUYT_O1WWr3U0hw', SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING)));
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+string(32) "aeb6798fef4e5184ff3b5596af753487"
+string(32) "aeb6798fef4e5184ff3b5596af753487"
+string(32) "aeb6798fef4e5184ff3b5596af753487"
+string(32) "aeb6798fef4e5184ff3b5596af753487"
+]]>
+   </screen>
+  </example><!-- }}} -->
+
+  <example xml:id="sodium-base642bin.example.ignore"><!-- {{{ -->
+   <title>Example of the <parameter>ignore</parameter> parameter</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$string = <<<'STR'
+    VGhpcyBpcy
+    BhbiBlbmNv
+    ZGVkIHN0cm
+    luZw==
+STR;
+var_dump(sodium_base642bin($string, SODIUM_BASE64_VARIANT_ORIGINAL, " \r\n"));
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+string(25) "This is an encoded string"
+]]>
+   </screen>
+  </example><!-- }}} -->
+ </refsect1><!-- }}} -->
+
+ <refsect1 role="seealso"><!-- {{{ -->
+  &reftitle.seealso;
+  <simplelist>
+   <member><function>base64_decode</function></member>
+   <member><function>sodium_bin2base64</function></member>
+   <member><function>sodium_bin2hex</function></member>
+  </simplelist>
+ </refsect1><!-- }}} -->
 
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/sodium/functions/sodium-bin2base64.xml b/reference/sodium/functions/sodium-bin2base64.xml
index 6995ba96f48c..3c18f9f3cc41 100644
--- a/reference/sodium/functions/sodium-bin2base64.xml
+++ b/reference/sodium/functions/sodium-bin2base64.xml
@@ -64,6 +64,59 @@
   </simpara>
  </refsect1>
 
+ <refsect1 role="examples"><!-- {{{ -->
+  &reftitle.examples;
+  <example xml:id="sodium-bin2base64.example.basic"><!-- {{{ -->
+   <title><function>sodium_bin2base64</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$string = 'This is an encoded string';
+echo sodium_bin2base64($string, SODIUM_BASE64_VARIANT_ORIGINAL);
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+VGhpcyBpcyBhbiBlbmNvZGVkIHN0cmluZw==
+]]>
+   </screen>
+  </example><!-- }}} -->
+
+  <example xml:id="sodium-bin2base64.example.id"><!-- {{{ -->
+   <title>Example of the <parameter>id</parameter> parameter</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+$binaryString = sodium_hex2bin('aeb6798fef4e5184ff3b5596af753487');
+var_dump(sodium_bin2base64($binaryString, SODIUM_BASE64_VARIANT_ORIGINAL));
+var_dump(sodium_bin2base64($binaryString, SODIUM_BASE64_VARIANT_ORIGINAL_NO_PADDING));
+var_dump(sodium_bin2base64($binaryString, SODIUM_BASE64_VARIANT_URLSAFE));
+var_dump(sodium_bin2base64($binaryString, SODIUM_BASE64_VARIANT_URLSAFE_NO_PADDING));
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+string(24) "rrZ5j+9OUYT/O1WWr3U0hw=="
+string(22) "rrZ5j+9OUYT/O1WWr3U0hw"
+string(24) "rrZ5j-9OUYT_O1WWr3U0hw=="
+string(22) "rrZ5j-9OUYT_O1WWr3U0hw"
+]]>
+   </screen>
+  </example><!-- }}} -->
+ </refsect1><!-- }}} -->
+
+ <refsect1 role="seealso"><!-- {{{ -->
+  &reftitle.seealso;
+  <simplelist>
+   <member><function>base64_encode</function></member>
+   <member><function>sodium_base642bin</function></member>
+   <member><function>sodium_hex2bin</function></member>
+  </simplelist>
+ </refsect1><!-- }}} -->
 
 </refentry>
 <!-- Keep this comment at the end of the file
diff --git a/reference/url/functions/base64-decode.xml b/reference/url/functions/base64-decode.xml
index 7262d2d5776e..e3fcd0bf1679 100644
--- a/reference/url/functions/base64-decode.xml
+++ b/reference/url/functions/base64-decode.xml
@@ -81,6 +81,7 @@ This is an encoded string
   <para>
    <simplelist>
     <member><function>base64_encode</function></member>
+    <member><function>sodium_base642bin</function></member>
     <member><link xlink:href="&url.rfc;2045">RFC 2045</link> section 6.8</member>
    </simplelist>
   </para>
diff --git a/reference/url/functions/base64-encode.xml b/reference/url/functions/base64-encode.xml
index c18baaf901f9..758f4f147ba4 100644
--- a/reference/url/functions/base64-encode.xml
+++ b/reference/url/functions/base64-encode.xml
@@ -76,6 +76,7 @@ VGhpcyBpcyBhbiBlbmNvZGVkIHN0cmluZw==
   <para>
    <simplelist>
     <member><function>base64_decode</function></member>
+    <member><function>sodium_bin2base64</function></member>
     <member><function>chunk_split</function></member>
     <member><function>convert_uuencode</function></member>
     <member><link xlink:href="&url.rfc;2045">RFC 2045</link> section 6.8</member>