substr

(PHP 4, PHP 5, PHP 7, PHP 8)

substrDevuelve parte de un string

Descripción

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

Devuelve una parte del string definida por los parámetros offset y length.

Parámetros

string

El string de entrada. Debe ser de almenos de un caracter.

offset

Si offset no es negativo, el string devuelto comenzará en el offset de la posición del string empezando desde cero. Por ejemplo, en el string 'abcdef', el carácter en la posición 0 es 'a', el carácter en la posición 2 es 'c', y así sucesivamente.

Si offset es negativo, el string devuelto empezará en offset contando desde el final de string.

Si la longitud del string es menor que offset, la función devolverá false.

Ejemplo #1 Usando un offset negativo

<?php
$rest
= substr("abcdef", -1); // devuelve "f"
$rest = substr("abcdef", -2); // devuelve "ef"
$rest = substr("abcdef", -3, 1); // devuelve "d"
?>

length

Si se especifica el length y es positivo, el string devuelta contendrá como máximo de caracteres de la cantidad dada por length que comienza en start (dependiedo de la longitud del string).

Si se especifica length es negativo, entonces ese número de caracteres se omiten al final del string (después de la posición inicial se ha calculado a start es negativo). Si start indica la posición de su truncamiento o más allá, se devolverá false.

Si se omite el length, el substring empezará por start hasta el final del string donde será devuelto.

Si se especifica length y es 0, false o null devolverá un string vacío.

Ejemplo #2 Usando un length negativo

<?php
$rest
= substr("abcdef", 0, -1); // devuelve "abcde"
$rest = substr("abcdef", 2, -1); // devuelve "cde"
$rest = substr("abcdef", 4, -4); // devuelve false
$rest = substr("abcdef", -3, -1); // devuelve "de"
?>

Valores devueltos

Devuelve la parte extraída de string; o un string vacío.

Historial de cambios

Versión Descripción
8.0.0 length es ahora anulable. Cuando length se establece explícitamente en null, la función devuelve un substring que termina al final del string, mientras que anteriormente devolvía un string vacío.
8.0.0 La función devuelve un string vacío donde anteriormente devolvía false.

Ejemplos

Ejemplo #3 Uso básico de substr()

<?php
echo substr('abcdef', 1); // bcdef
echo substr("abcdef", 1, null); // bcdef; Antes de PHP 8.0.0, se devolvía un string vacío.
echo substr('abcdef', 1, 3); // bcd
echo substr('abcdef', 0, 4); // abcd
echo substr('abcdef', 0, 8); // abcdef
echo substr('abcdef', -1, 1); // f

// El acceso a caracteres específicos en un string
// se puede conseguir usando "corchetes"
$string = 'abcdef';
echo
$string[0]; // a
echo $string[3]; // d
echo $string[strlen($string)-1]; // f

?>

Ejemplo #4 Comportamiento de casting de 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;
?>

El resultado del ejemplo sería:

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

Ejemplo #5 Rango de caracteres inválido

Si se solicita un rango de caracteres inválido, substr() devuelve un string vacío a partir de PHP 8.0.0; anteriormente, se devolvía false en su lugar.

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

Salida del ejemplo anterior en PHP 8:

string(0) ""

Salida del ejemplo anterior en PHP 7:

bool(false)

Ver también