str_pad()

La fonction PHP str_pad() complète une chaîne avec une autre chaîne jusqu'à atteindre une longueur donnée. Elle est utile chaque fois que la sortie doit avoir une largeur fixe : rembourrer des nombres avec des zéros (007), aligner des colonnes dans un rapport, construire des enregistrements à largeur fixe pour des systèmes anciens, ou centrer une étiquette dans une bannière.

Cette page couvre la syntaxe, chaque mode de rembourrage, les règles qui posent problème, et des exemples pratiques que vous pouvez exécuter.

Syntaxe

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

Paramètres

La fonction retourne la chaîne complétée. Elle ne tronque jamais — elle ne fait qu'allonger une chaîne ou la retourner telle quelle.

Exemple de base : rembourrer un nombre avec des zéros

Une utilisation courante est de forcer un nombre à une largeur fixe en le complétant avec des zéros en tête.

"Hello" fait 5 caractères et nous avons demandé une longueur de 10, donc str_pad() ajoute 5 caractères "0" à gauche :

00000Hello

Les trois modes de rembourrage

Le quatrième argument contrôle quel côté reçoit le rembourrage.

<?php
echo str_pad("Hi", 8, "-", STR_PAD_RIGHT), "\n"; // Hi------
echo str_pad("Hi", 8, "-", STR_PAD_LEFT),  "\n"; // ------Hi
echo str_pad("Hi", 8, "-", STR_PAD_BOTH),  "\n"; // ---Hi---
?>

Sortie :

Hi------
------Hi
---Hi---

Avec STR_PAD_BOTH, le rembourrage est réparti entre les deux côtés. Lorsque le nombre de caractères de rembourrage est impair, le caractère supplémentaire va à droite :

<?php
echo str_pad("Hi", 7, "-", STR_PAD_BOTH), "\n"; // --Hi---
?>

Exemple pratique : aligner un rapport

Comme str_pad() produit des colonnes à largeur fixe, elle est pratique pour les tableaux en texte brut. Complétez les libellés à droite et les nombres à gauche :

<?php
$items = ["Apples" => 3, "Bread" => 12, "Milk" => 1];

foreach ($items as $name => $qty) {
    echo str_pad($name, 10) . str_pad($qty, 5, " ", STR_PAD_LEFT) . "\n";
}
?>

Sortie :

Apples        3
Bread        12
Milk          1

Pièges et remarques

• Elle ne réduit jamais une chaîne. Si $length est inférieur à la longueur de l'entrée, str_pad() retourne l'entrée inchangée. Utilisez substr() si vous avez aussi besoin de limiter la longueur.
• Les chaînes de rembourrage multi-caractères peuvent dépasser la cible — mais str_pad() les coupe. Compléter "x" jusqu'à la longueur 6 avec "ab" donne "xababa" : la chaîne de rembourrage se répète et est coupée exactement à la longueur cible.
• Elle compte les octets, pas les caractères. Avec du texte multi-octets (UTF-8), un caractère accentué ou non-latin peut représenter plusieurs octets, donc la largeur visible peut différer de $length. Il n'existe pas de mb_str_pad() intégré avant PHP 8.3.
• Pour les nombres avec des zéros en tête, sprintf() avec un format comme %05d est souvent plus clair que str_pad().

Fonctions associées

• str_repeat() — répéter une chaîne un nombre fixe de fois.
• sprintf() — formater des chaînes avec des spécificateurs de largeur et de précision.
• number_format() — formater des nombres avec les milliers groupés et les décimales.
• strlen() — obtenir la longueur que str_pad() utilise comme référence.
• trim() — l'idée inverse : supprimer les caractères environnants.

Pratique