Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:127847
Precedence: bulk
MIME-Version: 1.0
References: <CAOV5rgZjxhe+75YD13wWFRNghbS4fbUrJVouPtbUv9RdpKSAXw@mail.gmail.com>
 <348856E5-6A4E-455A-81AE-882832170168@rwec.co.uk> <CAOV5rgaKkR-y3Hu9Fs0_ty2wT5MoYLDJ_OTH-nDBA-g__t4VEA@mail.gmail.com>
 <AE53E18F-A195-4D40-8BD1-D75AAFE07F92@rwec.co.uk> <CAOV5rgYNXLvBaBW50KpzNTFC7wEVBC0+QdSPmKhqsdGyc3uPWQ@mail.gmail.com>
 <38e57171-fc2e-4d79-8614-0b1c5a2efc72@app.fastmail.com>
In-Reply-To: <38e57171-fc2e-4d79-8614-0b1c5a2efc72@app.fastmail.com>
Date: Wed, 2 Jul 2025 21:25:03 +0200
Message-ID: <CAOV5rgbCVFHPivdKn7oWbKbOD9yaGXu2h5jgoGg9vmBz=mq3Gw@mail.gmail.com>
Subject: Re: [PHP-DEV] [RFC][DISCUSSION] Add RFC 4648 compliant data encoding API
To: Larry Garfield <larry@garfieldtech.com>, PHP Internals List <internals@lists.php.net>
Content-Type: multipart/alternative; boundary="00000000000076f5e70638f738ee"
From: nyamsprod@gmail.com (ignace nyamagana butera)

--00000000000076f5e70638f738ee
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

>
>
> I don't think it needs to be added to the enum, necessarily.  Just make i=
t
> a nullable argument to base64_decode.
>
> function base64_decode(string $string, bool $strict =3D false, ?DecodingM=
ode
> =3D null): string|false
>
> That would leave the default behavior of the function intact, but also
> allows switching it over to either of the new modes (which would then jus=
t
> defer to the new implementations).  And we wouldn't need to deal with
> "disallowed" modes on the new functions.
>
> Hi Larry,

The goal is not to change the signature of the existing `base64_encode`
function, but rather to preserve its current non-strict behavior within the
new API. This is intended to ensure a smoother transition from the existing
API to the proposed one. Therefore, we shouldn=E2=80=99t alter or retrofit =
the
existing function. Instead, the focus should be on providing a clear
migration path for users, which is why the addition of a
`DecodingMode::Unsafe` case is being proposed.

If I were to follow your suggestion, I would have proposed an alternative
signature like this:

```
base64_encode(string $string, bool|DecodingMode $strict =3D false);
```

Where:

 - `Encoding\DecodingMode::Strict` is identical to `$strict =3D true`
 - `Encoding\DecodingMode::Unsafe` would be identical to `$strict =3D false=
`

and the current function would then become an alias of

```
Encoding\base64_decode(string $encoded, decodingMode:
Encoding\DecodingMode::Unsafe);
// or
Encoding\base64_decode(string $encoded, decodingMode:
Encoding\DecodingMode::Strict);
```

The caveat is that, in the new API, errors will throw exceptions instead of
emitting an `E_WARNING` and returning `false`. Once the current API is
eventually removed, the `Encoding\DecodingMode::Unsafe` mode would also be
deprecated and removed accordingly. And documentation would rightly
highlight the danger of using such settings.

Keep in mind that this is in response to Rowan comment and depending on
feedback I may not add the `Encoding\DecodingMode::Unsafe` to the proposal.
I know I do not represent the majority but I tend to always use strict mode
when decoding base64 encoded data and when I forget PHPStan reminds me to
do so.

Best regards,
Ignace

--00000000000076f5e70638f738ee
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div class=3D"gmail_quote gmail_quote_container"><blockquo=
te class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px =
solid rgb(204,204,204);padding-left:1ex"><br>I don&#39;t think it needs to =
be added to the enum, necessarily.=C2=A0 Just make it a nullable argument t=
o base64_decode.<br>
<br>
function base64_decode(string $string, bool $strict =3D false, ?DecodingMod=
e =3D null): string|false<br>
<br>
That would leave the default behavior of the function intact, but also allo=
ws switching it over to either of the new modes (which would then just defe=
r to the new implementations).=C2=A0 And we wouldn&#39;t need to deal with =
&quot;disallowed&quot; modes on the new functions.<br><br></blockquote><div=
>Hi Larry,</div><div><br></div><div>The goal is not to change the signature=
 of the existing `base64_encode` function, but rather to preserve its curre=
nt non-strict behavior within the new API. This is intended to ensure a smo=
other transition from the existing API to the proposed one. Therefore, we s=
houldn=E2=80=99t alter or retrofit the existing function. Instead, the focu=
s should be on providing a clear migration path for users, which is why the=
 addition of a `DecodingMode::Unsafe` case is being proposed.</div><div><br=
></div><div>If I were to follow your suggestion, I would have proposed an a=
lternative signature like this:</div><div><br></div><div>```</div><div>base=
64_encode(string $string, bool|DecodingMode $strict =3D false);</div><div>`=
``</div><div><br></div><div>Where:</div><div><br></div><div>=C2=A0- `Encodi=
ng\DecodingMode::Strict` is identical to `$strict =3D true`</div><div>=C2=
=A0- `Encoding\DecodingMode::Unsafe` would=C2=A0be identical to `$strict =
=3D false`</div><div><br></div><div>and the current function would then bec=
ome an alias of=C2=A0</div><div><br></div><div>```</div><div>Encoding\base6=
4_decode(string $encoded, decodingMode: Encoding\DecodingMode::Unsafe);=C2=
=A0</div><div>// or</div><div><div>Encoding\base64_decode(string $encoded, =
decodingMode: Encoding\DecodingMode::Strict);</div>```</div><div><br></div>=
<div>The caveat is that, in the new API, errors will throw exceptions inste=
ad of emitting an `E_WARNING` and returning `false`. Once the current API i=
s eventually removed, the `Encoding\DecodingMode::Unsafe` mode would also b=
e deprecated and removed accordingly. And documentation would rightly highl=
ight the danger of using such settings.</div><div><br></div><div>Keep in mi=
nd that this is in response to Rowan comment and depending on feedback I ma=
y not add the `Encoding\DecodingMode::Unsafe` to the proposal. I know I do =
not represent the majority but I tend to always use strict mode when decodi=
ng base64 encoded data and when I forget PHPStan reminds me to do so.</div>=
<div><br></div><div>Best regards,</div><div>Ignace</div><div><br></div><div=
><br></div></div></div>

--00000000000076f5e70638f738ee--