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

Start at the htmlspecialchars_decode() entry point and reproduce the two PHP CLI examples from the report on PHP 8.1.2 or a comparable version. Check the linked htmlspecialchars_decode() manual entry and determine whether the documented ENT_SUBSTITUTE behavior should be implemented or removed; done means the behavior and documentation agree.