PHP Manual: str

Description

function str_pad(
    string $string,
    int $length,
    string $pad_string = " ",
    int $pad_type = STR_PAD_RIGHT
): string

This function returns the string string padded on the left, the right, or both sides to the specified padding length. If the optional argument pad_string is not supplied, the string is padded with spaces, otherwise it is padded with characters from pad_string up to the limit.

Parameters

string: The input string.
length: The desired length of the final padded string. If the value of length is negative, less than, or equal to the length of the input string, no padding takes place, and string will be returned.
pad_string: Note:
The pad_string may be truncated if the required number of padding characters can't be evenly divided by the pad_string's length.
pad_type: Optional argument pad_type can be STR_PAD_RIGHT, STR_PAD_LEFT, or STR_PAD_BOTH. If pad_type is not specified it is assumed to be STR_PAD_RIGHT.

Return Values

Returns the padded string.

Errors/Exceptions

Throws a ValueError if length is greater than the length of string and either pad_string is empty or pad_type is not STR_PAD_LEFT, STR_PAD_RIGHT or STR_PAD_BOTH.

Changelog

Version	Description
8.0.0	Now throws a ValueError if padding is needed and `pad_string` is empty or `pad_type` is invalid. Previously, an `E_WARNING` was raised and `null` was returned.

Examples

Example #1 str_pad() example

<?php
$input = "Alien";
echo str_pad($input, 10), PHP_EOL;                      // produces "Alien     "
echo str_pad($input, 10, "-=", STR_PAD_LEFT), PHP_EOL;  // produces "-=-=-Alien"
echo str_pad($input, 10, "_", STR_PAD_BOTH), PHP_EOL;   // produces "__Alien___"
echo str_pad($input,  6, "___"), PHP_EOL;               // produces "Alien_"
echo str_pad($input,  3, "*"), PHP_EOL;                 // produces "Alien"
?>