htmlspecialchars_decode() ENT_SUBSTITUTE flag has no effect

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 (archive) 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, 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

Commencez au point d’entrée htmlspecialchars_decode() et reproduisez les deux exemples PHP CLI du rapport avec PHP 8.1.2 ou une version comparable. Vérifiez l’entrée du manuel htmlspecialchars_decode() indiquée par le lien et déterminez si le comportement ENT_SUBSTITUTE documenté doit être implémenté ou supprimé ; le travail est terminé lorsque le comportement et la documentation concordent.