PHP Funções de String

Quase todo programa mexe com texto: um nome digitado num formulário, um e-mail, uma linha de um arquivo. O PHP traz prontas dezenas de funções para medir, procurar, trocar, cortar e arrumar textos. Nesta aula você conhece as mais usadas, uma de cada vez, sempre com a saída real do PHP.

Você já sabe o que é uma string (um texto entre aspas) e como juntar textos com o ponto (veja Operadores de String). Agora vamos trabalhar com esses textos. Os exemplos rodam com php arquivo.php no terminal da Ana (veja PHP na Linha de Comando) e você pode repetir todos no editor do guia.

Antes: o que é "chamar uma função"

Pense numa máquina de suco: você coloca laranjas (a entrada), aperta o botão e sai suco (o resultado). Você não precisa saber como a máquina funciona por dentro. Uma função do PHP é igual: você entrega um valor, ela faz um trabalho e devolve um resultado.

<?php
$nome = "Ana Souza";
echo strlen($nome), "\n";

strlen

O nome da função. Vem de string length, "comprimento do texto".

( )

Os parênteses dizem "execute a função agora". Sem eles, não é uma chamada.

$nome

O argumento: o valor que você entrega para a função trabalhar. Algumas funções recebem vários, separados por vírgula.

echo …

A função devolve um valor (aqui, o número 9), e o echo mostra esse valor na tela. Você também pode guardá-lo numa variável: $tamanho = strlen($nome);.

, "\n"

O echo aceita vários valores separados por vírgula. O "\n" é uma quebra de linha, para o prompt do terminal não grudar no resultado (veja echo e print).

$ php tamanho.php
9

Ana Souza tem 9 caracteres: 3 do "Ana", 1 espaço e 5 do "Souza". O espaço conta.

Medir e inverter

strlen: quantos caracteres?

<?php
$nome = "Ana Souza";
echo strlen($nome), "\n";
echo strlen(""), "\n";
echo strlen("  oi  "), "\n";

$ php medir.php
9
0         « texto vazio: zero
6         « os 4 espaços contam

Como no exemplo anterior, o "\n" depois de cada resultado só pula a linha.

str_word_count: quantas palavras?

<?php
echo str_word_count("Bom dia turma"), "\n";
echo str_word_count("Bom dia, turma!"), "\n";
echo str_word_count("Olá, você está aí?"), "\n";
print_r(str_word_count("Olá, você está aí?", 1));

$ php palavras.php
3
3          « vírgula e exclamação não atrapalham
4          « parece certo... mas veja as palavras que ele achou:
Array
(
    [0] => Ol
    [1] => voc
    [2] => est
    [3] => a
)

Com o segundo argumento 1, a função devolve a lista de palavras (um array, que o print_r mostra; veja var_dump e print_r). E a lista revela o problema: str_word_count só entende letras sem acento. O á de "Olá" foi tratado como separador, e "aí" virou só "a". O total deu 4 por sorte. Para português, prefira contar com explode (mais abaixo) ou com as técnicas da aula de mbstring.

strrev: texto ao contrário

<?php
echo strrev("Ana Souza"), "\n";
echo strrev("roma"), "\n";

$ php inverter.php
azuoS anA
amor

O nome vem de string reverse, "inverter o texto". Serve para brincadeiras (palíndromos: palavras que se leem igual de trás para frente). Assim como o strlen, ele não se dá bem com acentos: strrev("maçã") vira lixo, e a aula de mbstring mostra por quê.

Procurar dentro do texto

strpos: em que posição está?

strpos (de string position) procura um pedaço de texto dentro de outro e devolve a posição onde ele começa. A contagem começa do zero: o primeiro caractere é a posição 0, o segundo é a 1, e assim por diante.

<?php
$frase = "banana com canela";
var_dump(strpos($frase, "na"));
var_dump(strpos($frase, "com"));
var_dump(strpos($frase, "Com"));
var_dump(stripos($frase, "Com"));
var_dump(strrpos($frase, "na"));
var_dump(strpos($frase, "na", 3));
var_dump(strpos($frase, "uva"));

strpos($frase, "na")

Primeiro argumento: onde procurar (o "palheiro"). Segundo: o que procurar (a "agulha").

var_dump(…)

Mostra o valor e o tipo. Usamos var_dump e não echo porque o echo não mostra false (ele vira texto vazio).

$ php procurar.php
int(2)          « o primeiro "na" de "banana" começa na posição 2
int(7)
bool(false)     « "Com" com C maiúsculo não existe: strpos diferencia maiúsculas
int(7)          « stripos (i = ignora maiúsculas) acha
int(4)          « strrpos (r = right, da direita) acha o ÚLTIMO "na" de "banana"
int(4)          « o terceiro argumento manda começar a procurar da posição 3
bool(false)     « não achou: devolve false

Repare nos dois tipos de resposta: um número (int) quando acha, ou false quando não acha. É daí que vem a armadilha.

A armadilha do 0 × false

A Ana quer saber se um e-mail tem "ana" dentro. Ela escreve o que parece óbvio:

<?php
$email = "ana@escola.com.br";
if (strpos($email, "ana")) {
    echo "Achei 'ana'\n";
} else {
    echo "Não achei 'ana'\n";
}

$ php armadilha.php
Não achei 'ana'          « mas "ana" está bem ali no começo!

O que aconteceu, passo a passo:

1. "ana" está no começo do e-mail, na posição 0. O strpos devolveu 0.
2. O if precisa de verdadeiro ou falso. Ele converte o 0 em booleano, e 0 vira false (veja Booleanos).
3. O PHP foi para o else. Sem erro, sem aviso: só a resposta errada.

A correção é comparar com false, usando !== ("diferente e de tipo diferente"; veja Comparação (== e ===)). Assim, 0 (um int) não é confundido com false (um bool):

<?php
$email = "ana@escola.com.br";
if (strpos($email, "ana") !== false) {
    echo "Achei 'ana'\n";
} else {
    echo "Não achei 'ana'\n";
}

$ php armadilha-certa.php
Achei 'ana'

str_contains, str_starts_with, str_ends_with PHP 8.0+

Essas três funções respondem só "sim" ou "não". Os nomes já dizem tudo: "o texto contém…?", "começa com…?", "termina com…?".

<?php
$email = "ana@escola.com.br";
var_dump(str_contains($email, "@"));
var_dump(str_contains($email, "ANA"));
var_dump(str_contains($email, ""));
var_dump(str_starts_with($email, "ana"));
var_dump(str_ends_with($email, ".br"));
var_dump(str_ends_with("foto.JPG", ".jpg"));

$ php contem.php
bool(true)
bool(false)      « diferencia maiúsculas: "ANA" não é "ana"
bool(true)       « curiosidade: todo texto "contém" o texto vazio
bool(true)
bool(true)
bool(false)      « ".JPG" não é ".jpg"

Como elas já devolvem true ou false, o if fica natural: if (str_contains($email, "@")). Para ignorar maiúsculas, converta antes: str_ends_with(strtolower($arquivo), ".jpg").

<?php
$email = "ana@escola.com.br";

if (false) {   // troque o false por str_contains(...)
    echo "...";
} else {
    echo "...";
}

<?php
$email = "ana@escola.com.br";

if (str_contains($email, "@")) {
    echo "E-mail válido";
} else {
    echo "E-mail inválido";
}

Trocar: str_replace

str_replace ("substituir no texto") troca todas as ocorrências de um pedaço por outro. A ordem dos argumentos é: o que procurar, pelo que trocar, em qual texto.

<?php
echo str_replace("mundo", "Ana", "Olá, mundo!"), "\n";
echo str_replace("a", "4", "banana"), "\n";
echo str_replace("Banana", "Maçã", "banana e Banana"), "\n";
echo str_ireplace("banana", "maçã", "banana e Banana"), "\n";
echo str_replace(["á", "ã", "ç"], ["a", "a", "c"], "maçã e pão"), "\n";
str_replace("a", "o", "banana", $quantas);
echo "Trocas: $quantas\n";

$ php trocar.php
Olá, Ana!
b4n4n4                « trocou TODOS os "a"
banana e Maçã         « só o "Banana" com B maiúsculo
maçã e maçã           « str_ireplace ignora maiúsculas
maca e pao            « listas: cada item da primeira troca pelo item da segunda
Trocas: 3             « o 4º argumento recebe quantas trocas foram feitas

["á", "ã", "ç"]

Uma lista (array) do que procurar. O PHP troca o primeiro item pelo primeiro item da outra lista, o segundo pelo segundo…

$quantas

O quarto argumento é opcional. Você passa uma variável e a função a preenche com o número de trocas.

Agora o erro mais comum com str_replace (e com todas as funções desta aula):

<?php
$frase = "Olá, mundo!";
str_replace("mundo", "Ana", $frase);
echo $frase, "\n";

$ php esqueci.php
Olá, mundo!          « nada mudou!

O str_replace criou o texto novo Olá, Ana!, mas ninguém o guardou: ele foi jogado fora. A variável $frase continua igual. O certo é $frase = str_replace("mundo", "Ana", $frase);.

Cortar: substr

substr (de substring, "pedaço do texto") recorta uma parte. Você diz de onde começa e, se quiser, quantos caracteres pegar. A contagem começa do zero, como no strpos. Números negativos contam a partir do fim.

<?php
$nome = "Ana Souza";
echo substr($nome, 0, 3), "\n";
echo substr($nome, 4), "\n";
echo substr($nome, -5), "\n";
echo substr($nome, -5, 2), "\n";
echo substr($nome, 0, -6), "\n";
var_dump(substr($nome, 20));
echo $nome[0], "\n";
echo $nome[-1], "\n";

$ php cortar.php
Ana
Souza
Souza
So
Ana
string(0) ""
A
a

Um uso clássico: pegar as iniciais. substr("Ana", 0, 1) . substr("Souza", 0, 1) dá AS. Com nomes como "Érica", porém, substr corta a letra no meio; para isso existe o mb_substr (veja mbstring).

Maiúsculas e minúsculas

<?php
echo ucfirst("ana souza"), "\n";
echo ucwords("ana souza da silva"), "\n";
echo lcfirst("Ana"), "\n";
echo strtoupper("ana souza"), "\n";
echo strtolower("ANA SOUZA"), "\n";
echo ucwords(strtolower("ANA SOUZA")), "\n";
echo ucwords("ana-maria souza", " -"), "\n";

$ php maiusculas.php
Ana souza                « ucfirst: só a primeira letra do texto
Ana Souza Da Silva       « ucwords: a primeira letra de cada palavra
ana                      « lcfirst: primeira letra minúscula
ANA SOUZA                « strtoupper: tudo maiúsculo
ana souza                « strtolower: tudo minúsculo
Ana Souza                « funções encaixadas: primeiro minúsculo, depois capitaliza
Ana-Maria Souza          « o 2º argumento diz o que separa as palavras

Na linha ucwords(strtolower("ANA SOUZA")), uma função está dentro da outra. O PHP resolve de dentro para fora: primeiro strtolower devolve "ana souza", depois esse resultado entra no ucwords. Repare também que ucwords fez "Da Silva", com "Da" maiúsculo: ele não sabe que em português "da" fica minúsculo.

$ php -r 'echo ucfirst("érica"), " ", strtoupper("joão"), "\n";'
érica JOãO

Limpar espaços: trim

Quando alguém digita num formulário, é comum vir espaço sobrando no começo ou no fim (e às vezes um "Enter"). trim ("aparar") remove os espaços, tabs e quebras de linha das pontas. O meio fica intacto.

<?php
$digitado = "   Ana Souza  \n";
echo "[" . $digitado . "]\n";
echo "[" . trim($digitado) . "]\n";
echo "[" . ltrim($digitado) . "]\n";
echo "[" . rtrim($digitado) . "]\n";
echo "[" . trim("--Ana--", "-") . "]\n";

$ php aparar.php
[   Ana Souza
]                    « o original: espaços e um \n no fim
[Ana Souza]          « trim: as duas pontas
[Ana Souza
]                    « ltrim (left): só a esquerda
[   Ana Souza]       « rtrim (right): só a direita
[Ana]                « o 2º argumento diz QUAIS caracteres tirar

Os colchetes [ ] estão ali só para você ver onde o texto começa e termina. É um truque ótimo para depurar espaços invisíveis.

<?php
$digitado = "   aNA sOUZA  ";
$nome = $digitado;
echo "[" . $nome . "]";

<?php
$digitado = "   aNA sOUZA  ";
$nome = ucwords(strtolower(trim($digitado)));
echo "[" . $nome . "]";

Quebrar e juntar: explode e implode

explode ("explodir") quebra um texto em pedaços, cortando num separador, e devolve uma lista (array). implode faz o contrário: junta uma lista num texto só, com um "cola" entre os itens.

<?php
$linha = "maçã,banana,uva";
$frutas = explode(",", $linha);
print_r($frutas);
echo $frutas[1], "\n";
echo implode(" - ", $frutas), "\n";
echo implode(", ", ["pão", "leite", "café"]), "\n";

explode(",", $linha)

Primeiro o separador, depois o texto. Corta em cada vírgula.

$frutas[1]

Pega o item da posição 1 da lista (a contagem começa do zero). Arrays são o assunto de Arrays Indexados.

implode(" - ", $frutas)

Primeiro a cola, depois a lista. Junta os itens com - entre eles.

$ php quebrar.php
Array
(
    [0] => maçã
    [1] => banana
    [2] => uva
)
banana
maçã - banana - uva
pão, leite, café

Três detalhes que pegam muita gente:

<?php
print_r(explode(",", "maçã, banana, uva"));
print_r(explode(",", "a,b,c,d", 2));
print_r(explode(";", "sem separador"));

$ php quebrar2.php
Array
(
    [0] => maçã
    [1] =>  banana       « o espaço depois da vírgula veio junto!
    [2] =>  uva
)
Array
(
    [0] => a
    [1] => b,c,d         « o 3º argumento limita a 2 pedaços
)
Array
(
    [0] => sem separador « sem o separador: uma lista com o texto inteiro
)

No primeiro caso, o separador era só a vírgula, então o espaço ficou nos pedaços. Use explode(", ", …) ou passe cada pedaço pelo trim (você vai aprender a fazer isso para cada item em foreach e Funções de Array).

Completar e repetir: str_pad e str_repeat

str_pad ("acolchoar o texto") completa um texto até um tamanho, com o caractere que você escolher. É ótimo para números com zeros à esquerda e para alinhar colunas.

<?php
echo str_pad("7", 3, "0", STR_PAD_LEFT), "\n";
echo str_pad("Ana", 10, "."), "|\n";
echo str_pad("Ana", 10, ".", STR_PAD_LEFT), "|\n";
echo str_pad("Ana", 10, "*", STR_PAD_BOTH), "|\n";
echo str_pad("Ana Souza", 5, "."), "|\n";
echo str_repeat("-", 20), "\n";
echo str_repeat("ha", 3), "\n";

"7"

O texto original.

3

O tamanho final desejado.

"0"

Com o que completar (se você não disser, é um espaço).

STR_PAD_LEFT

De que lado completar: STR_PAD_RIGHT (direita, o padrão), STR_PAD_LEFT (esquerda) ou STR_PAD_BOTH (os dois). São constantes do PHP.

$ php completar.php
007
Ana.......|
.......Ana|
***Ana****|           « nos dois lados; quando sobra um, vai para a direita
Ana Souza|            « já era maior que 5: nada muda (str_pad nunca corta)
--------------------
hahaha

str_repeat ("repetir o texto") só repete um texto N vezes. É o jeito mais fácil de desenhar linhas e separadores na saída.

Quebrar linhas: wordwrap e nl2br

wordwrap: cabe na largura

wordwrap ("quebra de palavras") insere quebras para que nenhuma linha passe de uma largura, sem cortar palavras no meio.

<?php
$aviso = "Amanhã não haverá aula por causa da reunião de professores.";
echo wordwrap($aviso, 20, "\n"), "\n";

$ php quebra-linha.php
Amanhã não haverá
aula por causa da
reunião de
professores.

Argumentos: o texto, a largura máxima (20) e o que colocar na quebra ("\n"; numa página web, poderia ser "<br>"). Um quarto argumento true força o corte de palavras maiores que a largura, mas com acentos ele pode partir uma letra ao meio (veja mbstring).

nl2br: quebras de linha no HTML

No navegador, um \n dentro do HTML não pula linha: o navegador junta tudo. nl2br (new line to br, "quebra de linha para <br>") coloca um <br /> antes de cada quebra. É o que você usa para mostrar um texto digitado num <textarea>.

<?php
echo nl2br("Linha 1\nLinha 2"), "\n";

$ php nl2br.php
Linha 1<br />
Linha 2

No terminal você vê a tag <br />; no navegador, ela vira a quebra de linha. Quando o texto vem do usuário, a ordem certa é primeiro escapar, depois quebrar: nl2br(htmlspecialchars($texto)). O porquê está em Escapar a Saída (XSS).

<?php
$recado = "Ana,\nnão esqueça a reunião.\nAbraço!";
?>
<h3>Sem nl2br</h3>
<p><?= htmlspecialchars($recado) ?></p>
<h3>Com nl2br</h3>
<p><?= nl2br(htmlspecialchars($recado)) ?></p>

Quando dá errado

$ php armadilha.php
Não achei 'ana'

$ php erro-nome.php

Fatal error: Uncaught Error: Call to undefined function strlenght() in /home/ana/php/erro-nome.php:2
Stack trace:
#0 {main}
  thrown in /home/ana/php/erro-nome.php on line 2

<?php
echo strlen(null), "\n";
echo "fim\n";

$ php nulo.php

Deprecated: strlen(): Passing null to parameter #1 ($string) of type string is deprecated in /home/ana/php/nulo.php on line 2
0
fim

<?php
$frutas = ["maçã", "uva"];
echo strlen($frutas);

$ php lista.php

Fatal error: Uncaught TypeError: strlen(): Argument #1 ($string) must be of type string, array given in /home/ana/php/lista.php:3
Stack trace:
#0 {main}
  thrown in /home/ana/php/lista.php on line 3

$ php -r 'print_r(explode("", "Ana"));'

Fatal error: Uncaught ValueError: explode(): Argument #1 ($separator) must not be empty in Command line code:1
Stack trace:
#0 Command line code(1): explode('', 'Ana')
#1 {main}
  thrown in Command line code on line 1

Tabela das funções desta aula

A lista completa, com todas as opções, está na Referência: Funções de String.

Exercícios

<?php
$linha = "maçã,banana,uva";

echo $linha, "\n";

<?php
$linha = "maçã,banana,uva";
$frutas = explode(",", $linha);
echo implode(" | ", $frutas), "\n";
echo count($frutas), " frutas\n";

Resumo

• Uma função recebe argumentos entre parênteses e devolve um valor. As funções de string não mudam a variável: guarde o resultado ($s = trim($s);).
• strlen mede, strrev inverte, str_word_count conta palavras (mas não entende acentos).
• strpos devolve a posição (a partir de 0) ou false. Compare sempre com !== false.
• No PHP 8, para "sim ou não", use str_contains, str_starts_with e str_ends_with.
• str_replace troca, substr recorta (negativos contam do fim), trim limpa as pontas.
• ucfirst, ucwords, strtoupper, strtolower mudam maiúsculas, mas só das letras sem acento.
• explode quebra um texto em lista; implode junta uma lista num texto.
• str_pad completa, str_repeat repete, wordwrap quebra na largura, nl2br prepara quebras para o HTML.