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

Bắt đầu từ điểm vào htmlspecialchars_decode() và tái hiện hai ví dụ PHP CLI trong báo cáo trên PHP 8.1.2 hoặc một phiên bản tương đương. Kiểm tra mục hướng dẫn htmlspecialchars_decode() được liên kết và xác định xem hành vi ENT_SUBSTITUTE được ghi trong tài liệu nên được triển khai hay loại bỏ; công việc được xem là hoàn tất khi hành vi và tài liệu khớp nhau.