How to format a number with leading zeros in PHP

How to format a number with leading zeros in PHP

In PHP there are many ways in which we can manipulate strings and numbers in such a way for use for the task at hand. Each comes with its own way of handling and its own PHP internal functions, but one common number manipulation is padding a number with a leading set of numbers, typically this would be zeros. There might be many situations where you would want to pad a number. Number padding is what we'll refer to when we're appending numbers to the start of other numbers.

One example might be, that you have an order number within your internal system and you want all order numbers to be at least 8 digits in length. Here, if you had an online shop, an order number might be something like 58749, where you would likely want to number to be displayed to users like; 00058749. To do this we can use the internal PHP function str_pad.

Padding a number with zeros

str_pad(58749, 8, '0', STR_PAD_LEFT);
  • the first argument is the number you are modifying (type int)
  • the second argument is the total length of the number (type int)
  • the third argument is the string you want to append, in this case, '0' zeros (type string)
  • the final argument is which side of the pad should occur; in this case, the left side (appending) (type int: STR_PAD_RIGHT, STR_PAD_LEFT, or STR_PAD_BOTH. Default is: STR_PAD_RIGHT)

It's important to know this function will return a string, not a number. That's because this is a string function, not a number-only function. If you're strict within your code you can always typecast it back into an int.

Typecast str_pad into an int

Like before, this time typecasted.

$paddedNumber = (int) str_pad(58749, 8, '0', STR_PAD_LEFT);

If you're using PHP 7.3+ you should use str_pad however, anything PHP 7.1 or under should use sprintf as it's slightly faster.

Padding a number with leading zeros for PHP 7.1 or below

sprintf('%08d', 58749);

The first param is the resulting string; where "%" and "d" are the reserved keywords for sprintf.

The second parameter is the incoming number that we would like to change.

Alternative PHP 7.1 or below approach

If you have a fixed length or know the length of the string you're padding, you could use the str_repeat function, however, it is limited in its use. If the length of the string changes str_repeat won't natively be aware of this. You could get the string's length and adjust accordingly but when you have sprintf available or if you're running anything higher than 7.1 str_pad is a far better choice.

str_repeat("0", 3)."58749";

Negative Numbers and str_pad

It's important to note that whilst in the real world, padding out a negative number is likely uncommon, if you do with str_pad, you may get unexpected results.

echo str_pad(-58749, 8, '0', STR_PAD_LEFT);
# Results in
00-58749

And typecasting the above you give you;

echo (int) str_pad(-58749, 8, '0', STR_PAD_LEFT);
# Results in
0

Truncation with str_pad

Another thing to watch out for is the padded string value may get truncated if it cannot fit inside the required number of padding characters.

echo (int) str_pad(58749, 8, '1234', STR_PAD_LEFT);
# results in
12358749

Here the '4' has been truncated because it cannot fit within 8 characters. 123 + 58749. To avoid this, the input string (param 1) and the pad_string (param 3) should be less than or equal to the length (param 2).

On the flip side, if the input string is already bigger than the str_pad length, the input string will not change. Similar to the length, where if this is negative, less than, or equal to the input string, nothing occurs and the same input string is returned.

echo (int) str_pad(12345678, 8, '2', STR_PAD_LEFT);
# results in
12345678

str_pad Multibyte Support

In PHP 8.3, str_pad is getting its multibyte variant, mb_str_pad. Working the same way as str_pad, the mb_str_pad will support UTF-8 characters, including emojis. From version 8.3 of PHP, if you're looking to format numbers or multibyte strings, mb_str_pad is the function you're looking for!

Conclusion

Padding numbers in PHP is a useful technique when you want to ensure that numbers have a specific number of digits. That could be for display purposes or if you're trying to compare numbers against each other. Remember, padding numbers could affect number comparison, so make sure the way you pad numbers doesn't affect the overall purpose of your code, to avoid unwanted side effects.

  • Ensure the parameter order is correct to avoid output side effects
  • If using the optional pad type parameter use only STR_PAD_LEFT, STR_PAD_RIGHT, or STR_PAD_BOTH
  • Watch out for truncation with str_pad, when the length doesn't match the input string
  • In PHP 8.3, use mb_str_pad to pad multibyte strings
  • Use str_pad for aligning columns, fixing widths, formatting text, or order numbers to name just a few

Senior PHP developer. Author of Dev Lateral guides and tools. The complete place for PHP programmers. Available to hire to help you build or maintain your PHP application.

Looking for industry-leading PHP web development?

API development WordPress Hosting ★ and more 🐘

We use cookies to enhance your browsing experience, and analyse website traffic in accordance with our Privacy and Cookie Policy. Our cookies, including those provided by third parties, collect anonymous information about website usage and may be used for targeted advertising purposes. By clicking "Reject non-essential" you can opt out of non-essential cookies. By clicking "Accept all" you agree to the use of all cookies.


Reject non-essential Accept all