str_pad()

La funzione PHP str_pad() aggiunge una stringa a un'altra finché non raggiunge una lunghezza definita. La si utilizza quando l'output deve avere una larghezza fissa: zero-padding dei numeri (007), allineamento di colonne in un report, costruzione di record a larghezza fissa per sistemi legacy o centratura di un'etichetta all'interno di un banner.

Questa pagina illustra la sintassi, ciascuna modalità di riempimento, le regole che possono trarre in inganno e degli esempi pratici eseguibili.

Sintassi

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

Parametri

La funzione restituisce la stringa riempita. Non tronca mai — al limite allunga la stringa o la restituisce così com'è.

Esempio base: zero-padding di un numero

Un utilizzo comune è forzare un numero a una larghezza fissa aggiungendo zeri iniziali.

"Hello" è lunga 5 caratteri e abbiamo richiesto una lunghezza di 10, quindi str_pad() aggiunge 5 caratteri "0" a sinistra:

00000Hello

Le tre modalità di riempimento

Il quarto argomento controlla da quale lato viene aggiunto il riempimento.

<?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---
?>

Output:

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

Con STR_PAD_BOTH, il riempimento viene suddiviso tra i due lati. Quando il numero di caratteri di riempimento è dispari, quello in più va a destra:

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

Esempio pratico: allineamento di un report

Poiché str_pad() produce colonne a larghezza fissa, è utile per tabelle in testo semplice. Si riempiono le etichette a destra e i numeri a sinistra:

<?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";
}
?>

Output:

Apples        3
Bread        12
Milk          1

Note e avvertenze

• Non accorcia mai una stringa. Se $length è minore della lunghezza dell'input, str_pad() restituisce l'input invariato. Usa substr() se hai bisogno anche di limitare la lunghezza.
• Le stringhe di riempimento multi-carattere possono eccedere — ma str_pad() le taglia. Riempire "x" fino alla lunghezza 6 con "ab" produce "xababa": la stringa di riempimento si ripete e viene troncata esattamente alla lunghezza target.
• Conta i byte, non i caratteri. Con testo multibyte (UTF-8), un carattere accentato o non latino può occupare più byte, quindi la larghezza visibile può differire da $length. Non esiste un mb_str_pad() integrato prima di PHP 8.3.
• Per numeri con zero-padding, sprintf() con un formato come %05d è spesso più chiaro di str_pad().

Funzioni correlate

• str_repeat() — ripete una stringa un numero fisso di volte.
• sprintf() — formatta stringhe con specificatori di larghezza e precisione.
• number_format() — formatta numeri con separatori delle migliaia e decimali.
• strlen() — ottiene la lunghezza che str_pad() usa come riferimento.
• trim() — l'idea inversa: rimuove i caratteri circostanti.

Esercizio