substr

(PHP 4, PHP 5, PHP 7)

substrRetorna uma parte de uma string

Descrição

substr ( string $string , int $start [, int $length ] ) : string

Retorna a parte de string especificada pelo parâmetro start e length.

Parâmetros

string

A string de entrada. Deve ter ao menos um caracter.

start

Se start não for negativo, a string retornada iniciará na posição start em string, começando em zero. Por exemplo, na string 'abcdef', o caractere na posição 0 é 'a', o caractere na posição 2 é 'c', e assim em diante.

Se start for negativo, a string retornada irá começar no caractere start a partir do fim de string.

Se a string for mais curta que o parâmetro start, false will be returned.

Exemplo #1 Usando um início negativo

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

length

Se length for dado e for positivo, a string retornada irá conter length caracteres começando em start (dependendo do tamanho de string).

Se length for informado e for negativo, então esta quantidade caracteres serão omitidos do final de string (após a posicão de inicio ter sido calculada quando start for negativo). Se start denota uma posição além da truncagem, false will be returned.

Se length for informado como 0, false or null, uma string vazia será retornada.

Se length for omitido, a substring iniciando em start será retornada.

Exemplo #2 Usando um length negativo

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

Valor Retornado

Retorna a parte extraída da string; ou false em caso de falha, ou uma string vazia.

Changelog

Versão Descrição
7.0.0 Se string tiver o comprimento de start, uma string vazia será retornada. Antes dessa versão, retornava false nesse caso.
5.2.2 - 5.2.6 Se start indicar a posição de truncagem negativa ou além, retorna false. Outras versões retornavam a string a partir do começo.

Exemplos

Exemplo #3 Uso básico da substr()

<?php
echo substr('abcdef'1);     // bcdef
echo substr('abcdef'13);  // bcd
echo substr('abcdef'04);  // abcd
echo substr('abcdef'08);  // abcdef
echo substr('abcdef', -11); // f

// O acesso a caracteres individuais pode
// ser feito atravéz de indexação
$string 'abcdef';
echo 
$string[0];                 // a
echo $string[3];                 // d
echo $string[strlen($string)-1]; // f

?>

Exemplo #4 Comportamento de cast no substr()

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

echo 
"1) ".var_export(substr("pear"02), true).PHP_EOL;
echo 
"2) ".var_export(substr(5432102), true).PHP_EOL;
echo 
"3) ".var_export(substr(new apple(), 02), true).PHP_EOL;
echo 
"4) ".var_export(substr(true01), true).PHP_EOL;
echo 
"5) ".var_export(substr(false01), true).PHP_EOL;
echo 
"6) ".var_export(substr(""01), true).PHP_EOL;
echo 
"7) ".var_export(substr(1.2e304), true).PHP_EOL;
?>

O exemplo acima irá imprimir no PHP 7:

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

O exemplo acima irá imprimir no PHP 5:

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

Erros

Returns false on error.

<?php
var_dump
(substr('a'2)); // bool(false)
?>

Veja Também