[php-src] Issue #9582: htmlspecialchars_decode() ENT_SUBSTITUTE flag has no effect

Issue: https://github.com/php/php-src/issues/9582 Author: lucaswerkmeister ### Description The htmlspecialchars() function has an ENT_SUBSTITUTE flag (enabled by default since PHP 8.1) that changes its behavior when encountering invalid code unit sequences: ``` php > var_dump( htmlspecialchars( substr( 'abcdeä', 0, 6 ), 0 ) ); php shell code:1: string(0) "" php > var_dump( htmlspecialchars( substr( 'abcdeä', 0, 6 ), ENT_SUBSTITUTE ) ); php shell code:1: string(8) "abcde�" ``` htmlspecialchars_decode() is [documented](https://www.php.net/manual/en/function.htmlspecialchars-decode.php) ([archive](https://web.archive.org/web/20220421085844/https://www.php.net/manual/en/function.htmlspecialchars-decode.php)) to have the same flag, with the same effect, but actually it does nothing: ``` php > var_dump( htmlspecialchars_decode( substr( 'abcdeä', 0, 6 ), 0 ) ); php shell code:1: string(6) "abcde" php > var_dump( htmlspecialchars_decode( substr( 'abcdeä', 0, 6 ), ENT_SUBSTITUTE ) ); php shell code:1: string(6) "abcde" ``` (Appearance on your terminal may vary; it actually just returns the incomplete code unit sequence. On my system, in php -a it looks empty, while PsySH renders it as Ã.) [According to 3v4l](https://3v4l.org/aqXYO), this behavior has been the same since htmlspecialchars_decode() was introduced (from 5.1.0 all the way to 8.2rc2), so perhaps instead of changing the behavior, this should just be considered a documentation bug (remove the flag from the documentation)? ### PHP Version PHP 8.1.2 ### Operating System Ubuntu 22.04