>
> > Perhaps we should include an option in the new API to emulate the old
> behaviour, named as "legacy" or "unsafe" and immediately soft-deprecated
> with a note in the manual, similar to the MT_RAND_PHP mode in the
> Randomizer API <
> https://www.php.net/manual/en/random-engine-mt19937.construct.php>
If I follow your reasoning, this would imply introducing a new case,
`DecodingMode::Unsafe`, in the `DecodingMode` enum. This mode would
replicate the current default behavior of `base64_decode`, but only
within `Encoding\base64_decode`.
```php
echo base64_decode('dG9===0bw??'); // returns 'toto'
//would be portable to the new API using the following code
echo Encoding\base64_decode('dG9===0bw??', decodingMode:
Encoding\DecodingMode::Unsafe); // returns 'toto'
```
I would therefore propose that, for all other decoding functions, any
attempt to use `DecodingMode::Unsafe` must result in an
`UnableToDecodeException` being thrown.
Additionally, we should define the timeline for the eventual
deprecation of the current `base64_encode()`, `base64_decode()`,
`hex2bin()` and `bin2hex()` functions since the new option will be
automatically soft deprecated and removed at the same time as the
current API.
Should this deprecation take place during the PHP 8 cycle, with
removal targeted for PHP 9? Or would it be more appropriate to defer
the deprecation to the PHP 9 cycle, aiming for removal in PHP 10?
Alternatively, should a second vote be held to determine the
preferred deprecation timeline?
My intuition is that phasing out those functions during PHP 9 and
removing them in PHP 10 could help minimize disruption. However, I
don’t currently have data to support that assumption.
For completeness, the issue is less severe with `hex2bin` where a
transparent migration path is possible
```php
echo hex2bin('48656c6c6f2c20576f726c6421');
echo Encoding\base16_decode('48656c6c6f2c20576f726c6421',
decodingMode: Encoding\DecodingMode::Lenient);
// both codes will output: Hello, World
// whereas
echo Encoding\base16_decode('48656c6c6f2c20576f726c6421'); // will throw
