fix(api): utf8mb4 end-to-end + drop xajax-era entity decode in ban/comms flows

[rumblefrog]

Closes #1108.
Closes #1060. Closes #971. Closes #765.

Summary

• Default DB_CHARSET → utf8mb4 in web/init.php, web/config.php.template, web/phpstan-bootstrap.php, and the installer/updater templates so the panel's PDO handle issues SET NAMES utf8mb4 on every connection, matching the SourceMod plugin (sbpp_main.sp, sbpp_comms.sp) and the dev/CI schema charset. The 3-byte utf8 alias rejected supplementary-plane bytes and surfaced as Query_AddBlockInsert failed: Incorrect string value for the comms insert.
• Drop the legacy htmlspecialchars_decode / html_entity_decode dance from every API handler that reads a name / reason / chat message from a JSON body (api_bans_add, api_bans_paste, api_bans_kick_player, api_bans_send_message, api_bans_view_community, api_comms_add, api_comms_paste). xajax HTML-encoded payloads in transit; the JSON dispatcher does not. Decoding again collapsed a user-typed literal & into & and, combined with Smarty's auto-escape default (Enable automatic HTML escaping in Smarty templates #1087), produced the reported Can't get player info for <name> failure path.
• Replace compareSanitizedString($a, $b) with plain $a === $b at the five call sites and delete the helper from system-functions.php. Both sides of the comparison are raw UTF-8; wrapping them in htmlspecialchars first was only ever a no-op (or — for invalid UTF-8 — a source of false positives).
• Harden Api::dispatch() to pass JSON_INVALID_UTF8_SUBSTITUTE to json_encode. A single bad byte in a xpaw/php-source-query hostname/player name no longer collapses the whole response to false (the root cause of 1.8.0 Server webpage breaks if players have certain special characters. #971's "bad response" on the per-server tile).
• BanFlowTest grows a data-driven testBanRoundTripPreservesUnicodeAndAngleBrackets (four fixtures: CJK, angle brackets, Cyrillic+emoji, literal &), a testCommsAddPreservesUnicodeAndAngleBrackets, and a dispatcher-level testDispatcherSubstitutesInvalidUtf8InResponse guard.
• Doc sync: AGENTS.md anti-patterns list + ARCHITECTURE.md legacy-patterns table pick up the two new rows (no-decode-on-JSON-params, utf8mb4-end-to-end); the Database section in ARCHITECTURE.md calls out the charset convention explicitly.

Acceptance criteria

• Banning a connected player named 叮叮当当 succeeds via the panel. — testBanRoundTripPreservesUnicodeAndAngleBrackets data set cjk nickname (web/tests/integration/BanFlowTest.php:124) drives api_bans_add and asserts the raw string survives into sb_bans.name.
• Banning a player named =[BSID]= ethzero <Msg> succeeds and the <Msg> survives in the DB and renders escaped (not literal) in the ban list page. — Same dataprovider, angle brackets set. Round-trip asserts ban['name'] === "=[BSID]= ethzero <Msg>" (web/tests/integration/BanFlowTest.php:129). page_bans.tpl renders {$ban.player|smarty_stripslashes} under setEscapeHtml(true), so the stored <Msg> comes out as <Msg> in HTML (no nofilter was involved; see web/themes/default/page_bans.tpl:90,131).
• The per-server page loads when one of those names is connected. — api_servers_host_players passes player names verbatim into the JSON envelope; Api::dispatch now encodes with JSON_INVALID_UTF8_SUBSTITUTE (web/includes/Api.php:192), so a malformed or legacy-encoded byte sequence no longer produces an empty body. testDispatcherSubstitutesInvalidUtf8InResponse (web/tests/integration/BanFlowTest.php:177) guards the encoder behaviour.
• Comms block insert from the plugin works for the same names. — Plugin already runs SET NAMES utf8mb4 (game/addons/sourcemod/scripting/sbpp_main.sp:1098, sbpp_comms.sp:1384). The panel side now aligns: DB_CHARSET defaults to utf8mb4 in web/init.php:110, web/config.php.template:39, and web/phpstan-bootstrap.php:32; sb_bans.name, sb_bans.reason, sb_comms.name, and sb_comms.reason pick up character set utf8mb4 from the {charset} placeholder in web/install/includes/sql/struc.sql. testCommsAddPreservesUnicodeAndAngleBrackets (web/tests/integration/BanFlowTest.php:148) asserts 叮叮当当 <foo> round-trips through api_comms_add into both gag and mute rows.
• New integration test in web/tests/integration/BanFlowTest.php (or a sibling) asserts the round-trip and lands green in CI. — See the three new tests above (web/tests/integration/BanFlowTest.php:67–183). All 43 PHPUnit cases pass locally.

Test plan

• ./sbpp.sh phpstan — [OK] No errors (level 5, 168 files analysed, dba enabled against the live MariaDB).
• ./sbpp.sh test — 43 tests / 124 assertions, all green. New cases: Ban round trip preserves unicode and angle brackets ×4, Comms add preserves unicode and angle brackets, Dispatcher substitutes invalid utf 8 in response.
• ./sbpp.sh ts-check — silent pass (tsc --noEmit --checkJs on web/scripts/).
• ./sbpp.sh composer api-contract — regenerates web/scripts/api-contract.js; git diff clean (no handler signatures, perm masks, or registry entries changed).

Made with Cursor