Aspas simples
A maneira mais simples de se especificar uma string é
delimitá-la entre aspas simples (o caractere '
).
Para especificar um apóstrofo, escape-o com uma contrabarra
(\
). Para especificar uma contrabarra literal, duplique-a
(\\
). Todas as outras ocorrências da contrabarra serão tratadas
como uma contrabarra literal: isso significa que outras sequências de escape que
se esteja acostumado a utilizar, como \r
ou \n
, serão
literalmente impressas em vez de ter qualquer significado
especial.
Nota:
Diferentemente das sintaxes com aspas duplas
e heredoc,
variáveis e sequências de escape
para caracteres especiais não serão expandidas quando ocorrerem
dentro de uma string delimitada por aspas simples.
Heredoc
Uma terceira maneira de delimitar strings é a sintaxe heredoc:
<<<
. Após este operador, um identificador é
fornecido seguido de uma nova linha. A própria string é colocada em seguida e a seguir
o mesmo identificador novamente para fechar a string.
O identificador de fechamento pode ser indentado com espaços ou tabulações, e nesse caso
a indentação será removida de todas as linhas da doc string.
Anteriormente ao PHP 7.3.0, o identificador precisava
estar no começo da linha.
Além disso, o identificador de fechamento precisa seguir as mesmas convenções de nomes
de outros identificadores do PHP: ele precisa conter apenas caracteres alfanuméricos e
underlines, e precisa começar com uma letra ou underline.
Exemplo #1 Exemplo Heredoc simples no PHP 7.3.0
<?php
// Sem indentação
echo <<<END
a
b
c
\n
END;
// 4 espaços de indentação
echo <<<END
a
b
c
END;
Saída do exemplo acima no PHP 7.3:
Se o identificador de fechamento estiver identado diferentemente das linhas do corpo, um ParseError será lançado:
Exemplo #2 Identificador de fechamento indentado diferente das linhas do corpo
<?php
echo <<<END
a
b
c
END;
Saída do exemplo acima no PHP 7.3:
PHP Parse error: Invalid body indentation level (expecting an indentation level of at least 3) in example.php on line 4
Se o identificador de fechamento é identado, tabulações podem ser utilizados, no entanto
tabulações e espaços não podem estar misturados ou diferentes,
entre a indentação do fechamento e a indentação do corpo
Nesses casos, um ParseError será lançado.
Essas restrições de whitespace estão incluídas dados que a mistura de tabulações
e espaços são prejudiciais à legibilidade.
Exemplo #3 Indentação diferente entre corpo e fechamento
<?php
// Todos esses códidos falharão.
// Indentação diferente entre corpo (espaços) e fechamento (tabulações)
{
echo <<<END
a
END;
}
// Misturar tabulações e espaços no corpo
{
echo <<<END
a
END;
}
// Misturar espaços e tabulações no identficador de fechamento
{
echo <<<END
a
END;
}
Saída do exemplo acima no PHP 7.3:
PHP Parse error: Invalid indentation - tabs and spaces cannot be mixed in example.php line 8
O identificador de fechamento do corpo não necessita de um
ponto e vírgula ou nova linha. Por exemplo, o seguinte código
é permitido a partir do PHP7.3.0:
Exemplo #4 Continuando uma expressão após o identificador de fechamento
<?php
$values = [<<<END
a
b
c
END, 'd e f'];
var_dump($values);
Saída do exemplo acima no PHP 7.3:
array(2) {
[0] =>
string(11) "a
b
c"
[1] =>
string(5) "d e f"
}
Aviso
Se o identificador de fechamento for encontrado no começo da linha, existe
a ambiguidade de ele ser considerado ou não parte do texto, podendo
também ser considerado como fechamento, pode causar um ParseError.
Exemplo #5 Identificador de fechamento no corpo da string pode causar um ParseError
<?php
$values = [<<<END
a
b
END ING
END, 'd e f'];
Saída do exemplo acima no PHP 7.3:
PHP Parse error: syntax error, unexpected identifier "ING", expecting "]" in example.php on line 6
Para evitar esse problema, basta seguir a seguinte regra:
escolha identificadores que não aparecem no corpo
do texto.
Aviso
Anteriormente ao PHP 7.3.0, era muito importante notar que a linha com
o identificador de fechamento não poderia conter outros caracteres, exceto um ponto e vírgula
(;
).
Isso significava que o identificador de fechamento
não poderia ser identado, e que não poderia haver espaços
ou tabulações antes ou depois do ponto e vírgula. É importante notar também que
o primeiro caractere antes do fechamento deveria ser uma newline, como
definido pelo sistema operacional. Ou seja, \n
em
sistemas Unix, incluindo o macOS. O identificador de fechamento também
deveria ser seguido de um newline.
Se essa regra não for seguida, e o identificador de fechamento não estiver "limpo", ele
não será considerado como fechamento, e o PHP continuará lendo o script como se fosse
texto. Se um identificador de fechamento correto não for encontrado até o final do
arquivo, um erro de interpretação será lançado na última linha.
Exemplo #6 Exemplo inválido, antes do PHP 7.3.0
<?php
class foo {
public $bar = <<<EOT
bar
EOT;
}
// O identifcador não deve ser indentado
?>
Exemplo #7 Exemplo válido, mesmo antes do PHP 7.3.0
<?php
class foo {
public $bar = <<<EOT
bar
EOT;
}
?>
Heredocs não podem ser usados para inicializar propriedades de classe.
Textos heredoc se comportam como strings delimitadas por aspas duplas, sem
as aspas duplas. Isso significa que aspas simples em heredocs não precisam ser
escapadas, apesar de que os códigos de escape listados acima podem continuar sendo utilizados. Variáveis
são expandidas, mas o mesmo cuidado deve ser tomado ao expressar variáveis complexas
dentro do heredoc assim como nas strings.
Exemplo #8 Exemplo de delimitação de strings heredoc
<?php
$str = <<<EOD
Exemplo de uma string
distribuída em várias linhas
utilizando a sintaxe heredoc.
EOD;
/* Exemplo mais complexo, com variáveis */
class foo
{
var $foo;
var $bar;
function __construct()
{
$this->foo = 'Foo';
$this->bar = array('Bar1', 'Bar2', 'Bar3');
}
}
$foo = new foo();
$name = 'Meu nome';
echo <<<EOT
Meu nome é "$name". Eu estou imprimindo $foo->foo.
Agora, eu estou imprimindo {$foo->bar[1]}.
Isto deve imprimir um 'A' maiúsculo: \x41
EOT;
?>
O exemplo acima produzirá:
Meu nome é "Meu nome". Eu estou imprimindo Foo.
Agora, eu estou imprimindo Bar2.
Isto deve imprimir um 'A' maiúsculo: A
É possível também utilizar a sintaxe Heredoc para passar dados para argumentos de
funções:
Exemplo #9 Exemplo de Heredoc em argumentos
<?php
var_dump(array(<<<EOD
foobar!
EOD
));
?>
É possível inicializar variáveis estáticas e
propriedades/constantes de classe utilizando a sintaxe heredoc:
Exemplo #10 Utilizando o Heredoc na inicialização de valores estáticos
<?php
// Variáveis estáticas
function foo()
{
static $bar = <<<LABEL
Nada aqui...
LABEL;
}
// Classe propriedades/constantes
class foo
{
const BAR = <<<FOOBAR
Exemplo de constante
FOOBAR;
public $baz = <<<FOOBAR
Exemplo de propriedade
FOOBAR;
}
?>
O identificador de abertura do Heredoc pode ser opcionalmente
delimitado por aspas duplas:
Exemplo #11 Usando aspas duplas no Heredoc
<?php
echo <<<"FOOBAR"
Olá, mundo!
FOOBAR;
?>
Nowdoc
Nowdocs estão para aspas simples assim como os heredocs estão para aspas duplas em
strings. Um nowdoc é especificado similarmente a um heredoc, mas
nenhuma interpolação é feita dentro de um nowdoc. A construção é ideal para
colocar códigos PHP ou outros grandes blocos de texto sem a necessidade de
usar escapes. Compartilha algumas características em comum com a construção SGML
<![CDATA[ ]]>
, assim é declarado um bloco de
texto onde nada será analisado.
Um nowdoc é identificado com a mesma sequência <<<
usada para heredocs, mas o identificador precisa ficar entre
aspas simples, por exemplo. <<<'EOT'
. Todas as regras para
identificadores heredoc também se aplicam para identificadores nowdoc, especialmente aquelas
referentes a aparência do identificador de fechamento.
Exemplo #12 Exemplo de string em Nowdoc
<?php
echo <<<'EOD'
Exemplo de string abrangendo várias linhas
usando a sintaxe nowdoc. As barras invertidas são sempre tratadas literalmente,
por exemplo. \\ e \'.
EOD;
O exemplo acima produzirá:
Exemplo de string abrangendo várias linhas
usando a sintaxe nowdoc. As barras invertidas são sempre tratadas literalmente,
por exemplo. \\ e \'.
Exemplo #13 Exemplo de Nowdoc, com variáveis
<?php
class foo
{
public $foo;
public $bar;
function __construct()
{
$this->foo = 'Foo';
$this->bar = array('Bar1', 'Bar2', 'Bar3');
}
}
$foo = new foo();
$name = 'MyName';
echo <<<'EOT'
Meu nome é "$nome". Estou imprimindo alguns $foo->foo.
Agora, estou imprimindo alguns {$foo->bar[1]}.
Isso não deve imprimir um 'A' maiúsculo: \x41
EOT;
?>
O exemplo acima produzirá:
Meu nome é "$nome". Estou imprimindo alguns $foo->foo.
Agora, estou imprimindo alguns {$foo->bar[1]}.
Isso não deve imprimir um 'A' maiúsculo: \x41
Exemplo #14 Exemplo de dado estático
<?php
class foo {
public $bar = <<<'EOT'
bar
EOT;
}
?>
Interpolação de strings
Quando uma string é especificada dentro de aspas duplas ou heredoc,
as variáveis podem ser substituídas dentro dela.
Há dois tipos de sintaxe: uma
básica e uma
avançada.
A sintaxe básica é a mais comum e conveniente. Provê uma maneira de
incorporar uma variável, o valor de um array ou uma propriedade de object
em uma string com o mínimo de esforço.
Sintaxe básica
Se um sinal de cifrão ($
) for encontrado, os caracteres
que o seguem, e que podem ser usados em nome de variável, serão interpretados
como tal e substituídos.
Formalmente, a estrutura para a sintaxe básica de substituição de variável é
o seguinte:
Aviso
A sintaxe ${ expressão }
tornou-se defasada a partir do
PHP 8.2.0, já que pode ser interpretada como
variáveis variáveis:
A sintaxe
avançada
de interpolação de string deve ser usada em seu lugar.
Nota:
Se não for possível formar um nome válido, o símbolo de cifrão permanece
literalmente na string:
Exemplo #15 Interpolando o valor da primeira dimensão de um array ou propriedade
<?php
$sucos = array("maça", "laranja", "chave_string" => "roxo");
echo "Ele bebeu um pouco de suco de $sucos[0].";
echo PHP_EOL;
echo "Ele bebeu um pouco de suco de $sucos[1].";
echo PHP_EOL;
echo "Ele bebeu um pouco de suco de $sucos[chave_string].";
echo PHP_EOL;
class A {
public $s = "string";
}
$o = new A();
echo "Valor do objeto: $o->s.";
?>
O exemplo acima produzirá:
Ele bebeu um pouco de suco de maçã.
Ele bebeu um pouco de suco de laranja.
Ele bebeu um pouco de suco de roxo.
Valor do objeto: string.
Nota:
A chave do array deve ser sem aspas, e por isso não é possível
referenciar uma constante como chave com a sintaxe básica. Use a sintaxe
avançada
em seu lugar.
A partir do PHP 7.1.0 índices numéricos negativos são
suportados.
Exemplo #16 Índices numéricos negativos
<?php
$string = 'string';
echo "O caractere no índice -2 é $string[-2].", PHP_EOL;
$string[-3] = 'o';
echo "Alterar o caractere no índice -3 para 'o' dá $string.", PHP_EOL;
?>
O exemplo acima produzirá:
O caractere no índice -2 é n.
Alterar o caractere no índice -3 para o dá strong.
Para qualquer coisa mais complexa, a sintaxe
avançada
deve ser usada.
Sintaxe avançada (com chaves)
A sintaxe avançada permite a interpolação de
variáveis com acessadores arbitrários.
Qualquer variável escalar, elemento de array ou propriedade de objeto
(static ou não) com uma
representação de uma string pode ser incluída com essa sintaxe.
A expressão é escrita da mesma forma como apareceria fora da
string e então coloque-o entre {
e
}
. Já que que {
não pode escapado, esta
sintaxe será somente reconhecida quando o $
seguir,
imediatamente, o {
. Use {\$
para obter um literal
{$
. Alguns exemplos que tornam isto claro:
Nota:
Como esta sintaxe permite expressões arbitrárias, é possível usar
variáveis variáveis
dentro da sintaxe avançada.
Acesso e modificação da string por caractere
É possível acessar e modificar caracteres dentro de strings
especificando a posição, baseada em zero, do caractere desejado na
string usando colchetes, parecido com arrays, por exemplo
$str[42]. Imagine uma string como um
array de caracteres. As funções
substr() e substr_replace(),
podem ser utilizadas quando se deseja extrair ou substituir mais que 1 caractere.
Nota:
A partir do PHP 7.1.0, posições negativas para strings são suportadas. Estas especificam
a posição do final da string.
Antes, posições negativas emitiam um E_NOTICE
para leitura
(gerando um string vazia) e um E_WARNING
para escrita
(deixando a string intocada).
Nota:
Anteriormente ao PHP 8.0.0, strings também poderiam ser usados utilizandos chaves, por exemplo
$str{42}.
Essa sintaxe por chaves foi descontinuada desde o PHP 7.4.0 e não é mais suportadada a partir do PHP 8.0.0.
Aviso
Escrever em uma posição fora do intervalo preenche a string com espaços.
Tipos diferentes de inteiro são convertidos para inteiro.
Tipo ilegal de deslocamento emite um E_WARNING
.
Apenas o primeiro caractere de uma string atribuída é usado.
A partir de PHP 7.1.0, a atribuição de uma string vazia lança um erro fatal. Antes,
era atribuído o byte NULL.
Aviso
Internamente, as strings do PHP são arrays de bytes. Como resultado, acessar ou
modificar uma string usando colchetes não é seguro com multi-bytes e
deve ser feito somente em strings que utilizem apenas um byte em sua codificação,
como a ISO-8859-1.
Nota:
A partir do PHP 7.1.0, aplicar um operador de índice vazio em uma string lança um erro fatal
Antes, a string vazia era convertida em um array.
Exemplo #17 Alguns exemplos com strings
<?php
// Obtém o primeiro caractere de uma string
$str = 'Isto é um teste.';
$first = $str[0];
// Obtém o terceiro caractere de uma string
$third = $str[2];
// Obtém o último caractere de uma string
$str = 'Isto ainda é um teste.';
$last = $str[strlen($str)-1];
// Modifica o último caractere de uma string
$str = 'Olhe para a onda';
$str[strlen($str)-1] = 'e';
?>
Índices de strings dever ser inteiros ou strings parecidos com inteiros,
de outra forma um aviso é lançado.
Exemplo #18 Exemplo de índices inválidos em strings
<?php
$str = 'abc';
var_dump($str['1']);
var_dump(isset($str['1']));
var_dump($str['1.0']);
var_dump(isset($str['1.0']));
var_dump($str['x']);
var_dump(isset($str['x']));
var_dump($str['1x']);
var_dump(isset($str['1x']));
?>
O exemplo acima produzirá:
string(1) "b"
bool(true)
Warning: Illegal string offset '1.0' in /tmp/t.php on line 7
string(1) "b"
bool(false)
Warning: Illegal string offset 'x' in /tmp/t.php on line 9
string(1) "a"
bool(false)
string(1) "b"
bool(false)
Nota:
Acessar variáveis de outros tipos (excluindo-se arrays ou objetos que
implementem certas interfaces) usando []
ou
{}
silenciosamente retornará null
.
Nota:
Caracteres dentro de strings literais podem ser acessados
utilizando []
or {}
.
Nota:
Acessar caracteres em strings utilizando a sintax por
{}
foi descontinuada desde o PHP 7.4,
e não existe no PHP 8.0.