symfony/polyfill-mbstring · error · ValueError

mb_str_pad(): Argument #4 ($pad_type) must be STR_PAD_LEFT…

Error message

mb_str_pad(): Argument #4 ($pad_type) must be STR_PAD_LEFT, STR_PAD_RIGHT, or STR_PAD_BOTH

What it means

Mbstring::mb_str_pad() throws this ValueError when $pad_type is not one of STR_PAD_LEFT, STR_PAD_RIGHT, or STR_PAD_BOTH. The polyfill validates the pad type exactly as native PHP does; on PHP < 8.0 it raises an E_USER_WARNING and returns false instead.

Solutions

1. Pass exactly STR_PAD_LEFT, STR_PAD_RIGHT, or STR_PAD_BOTH
2. Map string config values ('left','right','both') to the constants before calling
3. in_array($pad_type, [STR_PAD_RIGHT, STR_PAD_LEFT, STR_PAD_BOTH], true) check before calling
4. Catch \ValueError on PHP 8+ or rely on warning/false on PHP < 8

Example fix

// before
mb_str_pad($s, 10, '.', 'right');
// after
mb_str_pad($s, 10, '.', STR_PAD_RIGHT);

$map = ['left' => STR_PAD_LEFT, 'right' => STR_PAD_RIGHT, 'both' => STR_PAD_BOTH];
$padType = $map[strtolower((string) $padType)] ?? STR_PAD_RIGHT;
mb_str_pad($string, $length, $padString, $padType);

function isValidPadType($padType): bool
{
    return in_array($padType, [STR_PAD_LEFT, STR_PAD_RIGHT, STR_PAD_BOTH], true);
}

try {
    $padded = mb_str_pad($s, $len, $pad, $padType);
} catch (\ValueError $e) {
    $padded = mb_str_pad($s, $len, $pad, STR_PAD_RIGHT);
}

When it happens

Trigger: Calling mb_str_pad($s, $len, $pad, 4), an arbitrary integer, a string like 'left', or an out-of-scope constant; passing a constant defined by another library that happens to collide numerically.

Common situations: Pad type read from config as a string ('left'/'right') instead of the STR_PAD_* constants; typos or invalid mapping tables translating user options to pad types; copying code using constants that don't exist in scope.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Argument #1 ($encoding) must be a valid encoding
• Argument #1 ($language) must be a valid language
• Argument #2 ($length) must be greater than 0
• Argument #1 ($substitute_character) must be "none", "long"…
• mb_str_pad(): Argument #3 ($pad_string) must be a non-empty…

AI-assisted analysis of symfony/polyfill-mbstring@d3d318bad5 (2026-09-13). Data as JSON: /api/errors/426b7b8440219040. Report an issue: GitHub.

Appendix: source

Thrown at Mbstring.php:913

        if (self::mb_strlen($pad_string, $encoding) <= 0) {
            if (\PHP_VERSION_ID < 80000) {
                trigger_error('mb_str_pad(): Argument #3 ($pad_string) must be a non-empty string', \E_USER_WARNING);

                return false;
            }

            throw new \ValueError('mb_str_pad(): Argument #3 ($pad_string) must be a non-empty string');
        }

        if (!\in_array($pad_type, [\STR_PAD_RIGHT, \STR_PAD_LEFT, \STR_PAD_BOTH], true)) {
            if (\PHP_VERSION_ID < 80000) {
                trigger_error('mb_str_pad(): Argument #4 ($pad_type) must be STR_PAD_LEFT, STR_PAD_RIGHT, or STR_PAD_BOTH', \E_USER_WARNING);

                return false;
            }

            throw new \ValueError('mb_str_pad(): Argument #4 ($pad_type) must be STR_PAD_LEFT, STR_PAD_RIGHT, or STR_PAD_BOTH');
        }

        $paddingRequired = $length - self::mb_strlen($string, $encoding);

        if ($paddingRequired < 1) {
            return $string;
        }

        switch ($pad_type) {
            case \STR_PAD_LEFT:
                return self::mb_substr(str_repeat($pad_string, $paddingRequired), 0, $paddingRequired, $encoding).$string;
            case \STR_PAD_RIGHT:
                return $string.self::mb_substr(str_repeat($pad_string, $paddingRequired), 0, $paddingRequired, $encoding);
            default:
                $leftPaddingLength = floor($paddingRequired / 2);
                $rightPaddingLength = $paddingRequired - $leftPaddingLength;

                return self::mb_substr(str_repeat($pad_string, $leftPaddingLength), 0, $leftPaddingLength, $encoding).$string.self::mb_substr(str_repeat($pad_string, $rightPaddingLength), 0, $rightPaddingLength, $encoding);

View on GitHub (pinned to d3d318bad5)