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

htmlspecialchars_decode() のエントリーポイントから始め、PHP 8.1.2 または同等のバージョンで、報告にある 2 つの PHP CLI の例を再現してください。リンクされている htmlspecialchars_decode() のマニュアル項目を確認し、文書化されている ENT_SUBSTITUTE の動作を実装するべきか削除するべきかを判断してください。動作とドキュメントが一致すれば完了です。