Description

substr(string $string, int $offset, ?int $length = null): string

Retourne le segment de string défini par offset et length.

Liste de paramètres

string

offset

Si offset est positif, la chaîne retournée commencera au caractère numéro offset, dans la chaîne string. Le premier caractère est numéroté zéro. En effet, dans la chaîne 'abcdef', le caractère à la position 0 est 'a', le caractère à la position 2 est 'c', et ainsi de suite.

Si offset est négatif, la chaîne retournée commencera au caractère numéro offset à compter de la fin de la chaîne string.

Si string est plus petit que offset caractères de long, une chaîne vide sera retournée.

Exemple #1 Exemple de offset négatif

<?php
echo substr("abcdef", -1), PHP_EOL;    // retourne "f"
echo substr("abcdef", -2), PHP_EOL;    // retourne "ef"
echo substr("abcdef", -3, 1), PHP_EOL; // retourne "d"
?>

length

Si length est fourni et est positif, la chaîne retournée contiendra au plus length caractères, en commençant à partir du caractère offset (en fonction de la taille de la chaîne string).

Si length est fourni et négatif, alors le même caractère sera omis de la fin de string. Si offset indique la position de cette troncature ou une position hors de la chaîne, une chaîne vide sera retournée.

Si le paramètre length est fourni et vaut 0, une chaîne vide sera retournée.

Si length est omis ou null, la sous chaîne commençant à partir de offset jusqu'à la fin sera retournée.

Exemple #2 Utilisation d'une valeur négative pour length

<?php
echo substr("abcdef", 0, -1), PHP_EOL;  // retourne "abcde"
echo substr("abcdef", 2, -1), PHP_EOL;  // retourne "cde"
echo substr("abcdef", 4, -4), PHP_EOL;  // retourne ""; antérieur à PHP 8.0.0, false était retourné
echo substr("abcdef", -3, -1), PHP_EOL; // retourne "de"
?>

Valeurs de retour

Retourne la partie extraite de la chaîne string, ou une chaîne vide.

Historique

Version	Description
8.0.0	`length` est désormais nullable. Lorsque `length` est explicitement défini à `null`, la fonction retourne une sous-chaîne terminant à la fin de la chaîne, alors qu'elle renvoyait auparavant une chaîne vide.
8.0.0	Cette fonction retourne une chaîne vide où auparavant elle retournait `false`

Exemples

Exemple #3 Exemple avec substr()

<?php
echo substr('abcdef', 1), PHP_EOL;     // bcdef
echo substr("abcdef", 1, null), PHP_EOL; // bcdef; antérieur à PHP 8.0.0, une chaîne vide était retournée
echo substr('abcdef', 1, 3), PHP_EOL;  // bcd
echo substr('abcdef', 0, 4), PHP_EOL;  // abcd
echo substr('abcdef', 0, 8), PHP_EOL;  // abcdef
echo substr('abcdef', -1, 1), PHP_EOL; // f

// Accéder à un simple caractère dans une chaîne
// peut également être réalisé en utilisant des crochets
$string = 'abcdef';
echo $string[0], PHP_EOL;                 // a
echo $string[3], PHP_EOL;                 // d
echo $string[strlen($string)-1], PHP_EOL; // f

?>

Exemple #4 Comportement du cast avec substr()

<?php
class apple {
    public function __toString() {
        return "green";
    }
}

echo "1) ", var_export(substr("pear", 0, 2), true), PHP_EOL;
echo "2) ", var_export(substr(54321, 0, 2), true), PHP_EOL;
echo "3) ", var_export(substr(new apple(), 0, 2), true), PHP_EOL;
echo "4) ", var_export(substr(true, 0, 1), true), PHP_EOL;
echo "5) ", var_export(substr(false, 0, 1), true), PHP_EOL;
echo "6) ", var_export(substr("", 0, 1), true), PHP_EOL;
echo "7) ", var_export(substr(1.2e3, 0, 4), true), PHP_EOL;
?>

L'exemple ci-dessus va afficher :

1) 'pe'
2) '54'
3) 'gr'
4) '1'
5) ''
6) ''
7) '1200'

Exemple #5 Intervalle de Caractères Invalide

Si un intervalle de caractères invalide est demandé, substr() retourne une chaîne vide à partir de PHP 8.0.0; auparavant false était retourné à la place.

<?php
var_dump(substr('a', 2));
?>

Résultat de l'exemple ci-dessus en PHP 8 :

string(0) ""

Résultat de l'exemple ci-dessus en PHP 7 :

bool(false)

Voir aussi

strrchr() - Trouve la dernière occurrence d'un caractère dans une chaîne
substr_replace() - Remplace un segment dans une chaîne
preg_match() - Effectue une recherche de correspondance avec une expression rationnelle standard
trim() - Supprime les espaces (ou d'autres caractères) en début et fin de chaîne
mb_substr() - Lit une sous-chaîne
wordwrap() - Effectue la césure d'une chaîne
Accès et modification d'une chaîne, par caractère