{"record":{"id":"9cb51aaa51622c50","repo":"symfony/polyfill-mbstring","slug":"argument-1-substitute-character-must-be-none-long-entity-or","errorCode":null,"errorMessage":"Argument #1 ($substitute_character) must be \"none\", \"long\", \"entity\" or a valid codepoint","messagePattern":"Argument #1 \\(\\$substitute_character\\) must be \"none\", \"long\", \"entity\" or a valid codepoint","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"Mbstring.php","lineNumber":679,"sourceCode":"        return self::mb_convert_case($s, \\MB_CASE_UPPER, $encoding);\n    }\n\n    public static function mb_substitute_character($c = null)\n    {\n        if (null === $c) {\n            return 'none';\n        }\n        if (0 === strcasecmp($c, 'none')) {\n            return true;\n        }\n        if (80000 > \\PHP_VERSION_ID) {\n            return false;\n        }\n        if (\\is_int($c) || 'long' === $c || 'entity' === $c) {\n            return false;\n        }\n\n        throw new \\ValueError('Argument #1 ($substitute_character) must be \"none\", \"long\", \"entity\" or a valid codepoint');\n    }\n\n    public static function mb_substr($s, $start, $length = null, $encoding = null)\n    {\n        $encoding = self::getEncoding($encoding);\n        if ('CP850' === $encoding || 'ASCII' === $encoding) {\n            return (string) substr($s, $start, null === $length ? 2147483647 : $length);\n        }\n\n        if ($start < 0) {\n            $start = iconv_strlen($s, $encoding) + $start;\n            if ($start < 0) {\n                $start = 0;\n            }\n        }\n\n        if (null === $length) {\n            $length = 2147483647;","sourceCodeStart":661,"sourceCodeEnd":697,"githubUrl":"https://github.com/symfony/polyfill-mbstring/blob/d3d318bad5e7a1bfbd026009c8bfb8d8f99ae6b6/Mbstring.php#L661-L697","documentation":"Mbstring::mb_substitute_character() throws this ValueError when $substitute_character is not 'none', 'long', 'entity', or a valid integer codepoint. On PHP < 8.0 the polyfill returns false instead of throwing.","triggerScenarios":"Calling mb_substitute_character('invalid') or with a string other than the three accepted keywords, e.g. mb_substitute_character('?') — a common mistake since the native function once accepted form characters; passing a numeric string like '63' instead of the int 63.","commonSituations":"Config files storing the substitute char as a string like '?' or '63'; porting code from PHP < 8 where mb_substitute_character accepted a string form char; validating HTTP Accept-Charset derived settings.","solutions":["Pass exactly 'none', 'long', or 'entity' (string), or a valid integer codepoint such as 63 for '?'","Convert numeric strings to int before calling: (int) $value","Whitelist/normalize config values before applying them","Catch \\ValueError on PHP 8+ or check the false return on PHP < 8"],"exampleFix":"// before\nmb_substitute_character('?');\n// after\nmb_substitute_character(63); // integer codepoint for '?'","handlingStrategy":"validation","validationCode":"$allowed = ['none','long','entity'];\nif (!in_array($c, $allowed, true) && !is_int($c)) {\n    $c = is_numeric($c) ? (int) $c : 'none';\n}\nmb_substitute_character($c);","typeGuard":"function isValidSubstituteCharacter($c): bool\n{\n    return is_int($c) || in_array($c, ['none','long','entity'], true);\n}","tryCatchPattern":"try {\n    mb_substitute_character($c);\n} catch (\\ValueError $e) {\n    mb_substitute_character('none');\n}","preventionTips":["Only pass 'none','long','entity' or an int codepoint — never a string form char","Convert numeric strings from config to int","Whitelist config values before applying","Note behavior differs below PHP 8 (false return, no throw)"],"tags":["php","mbstring","polyfill","valueerror","substitute-character"],"backgroundTag":"invalid-enum-value","analyzedSha":"d3d318bad5e7a1bfbd026009c8bfb8d8f99ae6b6","analyzedAt":"2026-09-13T19:34:02.044Z","contentChangedAt":"2026-09-13T19:34:02.044Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}