When you need to extend a string to a desired byte length, it helps to understand both the normal result and what changes with different inputs. This guide focuses on practical examples rather than repeating PHP background material.
str_pad provides the behavior described below. Padding may be added on the left, right or both sides. Strings longer than the target are not truncated.
What Is str_pad in PHP?
Extend a string to a desired byte length. Padding may be added on the left, right or both sides. Strings longer than the target are not truncated.
Its syntax is:
str_pad(string $string, int $length, string $pad_string = ..., int $pad_type = ...): string
Parameters and return value: Read the argument names and optional values in the signature above. Methods use an existing object, while stand-alone functions take direct arguments. The examples demonstrate the relevant arguments and the value returned or the object modified.
Important: Length is measured in bytes, not visible Unicode characters. The padding string cannot be empty.
Example 1: Basic Usage
This first example demonstrates how to extend a string to a desired byte length with a small input.
<?php
echo str_pad("42", 6, "0", STR_PAD_LEFT);
Output:
000042
The example uses the simplest useful form. Padding may be added on the left, right or both sides. Strings longer than the target are not truncated. The output may depend on the active ICU locale, PHP configuration, or input supplied to the function.
Example 2: Another Case
Here the input or option changes, making it easier to see where the behavior differs. Length is measured in bytes, not visible Unicode characters. The padding string cannot be empty.
<?php
echo "[" . str_pad("OK", 8, ".", STR_PAD_BOTH) . "]";
Output:
[...OK...]
Compare the result to the first example. sprintf() can format numeric width; mb_* functions help count multilingual text.
Practical Example: Applying the Function
This standalone example shows how the same operation fits into a small application task.
<?php
$referenceNumbers = [3, 45, 712];
foreach ($referenceNumbers as $referenceNumber) {
echo "Order-" . str_pad((string) $referenceNumber, 5, "0", STR_PAD_LEFT) . PHP_EOL;
}
Output:
Order-00003
Order-00045
Order-00712
The example keeps the operation visible and gives you a starting point for using it in an application. Length is measured in bytes, not visible Unicode characters. The padding string cannot be empty.
Important Behavior and Edge Cases
- Core behavior: Padding may be added on the left, right or both sides. Strings longer than the target are not truncated.
- Return value: Check the result separately from changes to passed-in arrays, iterators, or object state.
- Data constraints: Length is measured in bytes, not visible Unicode characters. The padding string cannot be empty.
- Environment: Run this example under a PHP version supporting the API; check results and exceptions before using them.
Comparison With Related Functions
| Function or Approach | When to Use It |
|---|---|
str_pad | Extend a string to a desired byte length. |
| Related PHP APIs | sprintf() can format numeric width; mb_* functions help count multilingual text. |
Common Beginner Mistakes
| Mistake | Correct Approach |
|---|---|
| Assuming the function works on every kind of input | Follow the declared argument types and check the input format before calling it. |
| Ignoring the behavior of the result | Length is measured in bytes, not visible Unicode characters. The padding string cannot be empty. |
| Using the wrong related PHP API | sprintf() can format numeric width; mb_* functions help count multilingual text. |
Key Takeaways
str_padhelps you extend a string to a desired byte length.- Padding may be added on the left, right or both sides. Strings longer than the target are not truncated.
- Length is measured in bytes, not visible Unicode characters. The padding string cannot be empty.
- sprintf() can format numeric width; mb_* functions help count multilingual text.
str_pad is useful when you need to extend a string to a desired byte length. Start with the small examples, then adapt the practical example while respecting its input and environment requirements.