PHP RFC: mb_str_pad

• Version: 0.1
• Date: 2023-05-19
• Author: Niels Dossche (nielsdos), dossche.niels@gmail.com
• Status: Draft
• First Published at: http://wiki.php.net/rfc/mb_str_pad

Many string functions in PHP come in two different variants: one for byte strings, and one for multibyte strings. This RFC proposes the addition of mb_str_pad to PHP as a multibyte equivalent of the existing str_pad function. The current str_pad function lacks multibyte character support, causing issues when working with languages that utilize multibyte encodings like UTF-8.

The proposal is to introduce a new mbstring function mb_str_pad(). The function follows the same signature as the str_pad() function, except that it has an additional argument for the string encoding. The encoding argument works analogously to the other mbstring functions. The argument applies on both the $input string and the $pad_string. If null, the default mbstring encoding is used. The $pad_type argument can take three possible values: STR_PAD_LEFT, STR_PAD_RIGHT, STR_PAD_BOTH. These are the same constants as in str_pad().

function mb_str_pad(string $string, int $length, string $pad_string = " ", int $pad_type = STR_PAD_RIGHT, ?string $encoding = null): string {}

The error conditions for this function are the same as for str_pad():

• $pad must not be an empty string. Otherwise it will result in a value error.
• $pad_type must be one of STR_PAD_LEFT, STR_PAD_RIGHT, STR_PAD_BOTH. Otherwise it will result in a value error.

Since this is a new function, and no existing functions change, the risk of a BC break is minimal. The only break occurs when a userland PHP project defines their own mb_str_pad() function without first checking if PHP itself does not define one. TODO

Next PHP 8.x (at the time of writing this is PHP 8.3).

None.

mbstring: A new function mb_str_pad() will be added to mbstring. The implementation of this function will leverage the existing internal functions of mbstring. No modifications will be made to any existing functions, and no new internal functions will be added. By reusing existing internal functions, the maintenance burden of mb_str_pad() stays quite low.

None.

None.

None.

Make sure there are no open issues when the vote starts!

Everything outside of mbstring.

None.

One primary yes/no vote to decide if the function may be introduced.

Implementation: https://github.com/nielsdos/php-src/tree/mb_str_pad

After the project is implemented, this section should contain

1. the version(s) it was merged into
2. a link to the git commit(s)
3. a link to the PHP manual entry for the feature
4. a link to the language specification section (if any)

Original issue report suggesting this feature: https://github.com/php/php-src/issues/10203

Keep this updated with features that were discussed on the mail lists.