strtr()

Introdução

A função strtr() em PHP traduz substrings dentro de uma string. É particularmente útil para processamento de texto quando sequências específicas precisam ser substituídas de forma eficiente. Este artigo aborda sua sintaxe, comportamento e uso prático.

Entendendo a função strtr()

A função strtr() suporta duas assinaturas:

Assinatura com array

strtr(string $str, array $replace) : string

Aqui, $str é a string de entrada e $replace é um array associativo que mapeia substrings às suas substituições. A função substitui todas as ocorrências das chaves pelos valores correspondentes.

Assinatura com três argumentos

strtr(string $str, string $from, string $to) : string

Nesta forma, $from e $to devem ter o mesmo comprimento. Cada caractere em $from é mapeado para o caractere na mesma posição em $to.

Comportamento importante: strtr() substitui substrings usando um algoritmo de correspondência mais longa primeiro. Isso significa que padrões sobrepostos são resolvidos priorizando a correspondência mais longa, e as substituições não são aplicadas recursivamente à saída.

Forma com array: substituindo substrings

O uso mais comum de strtr() é a forma de dois argumentos com array. Você passa um array associativo que mapeia cada substring que deseja encontrar para o valor pelo qual ela deve ser substituída.

Aqui strtr() substitui cada "H" por "J" e cada "W" por "Z". As chaves podem ter qualquer comprimento, então você pode mapear palavras inteiras com a mesma facilidade que caracteres individuais:

<?php

$string = "The quick brown fox";
echo strtr($string, ["quick" => "slow", "brown" => "red"]);
// Output: The slow red fox

As substituições são aplicadas em uma única passagem

Este é o comportamento que confunde as pessoas. strtr() percorre a string uma única vez e nunca reexamina o texto que já foi substituído. Portanto, um valor inserido não será correspondido novamente por outra regra:

<?php

echo strtr("Hi all, I said hello", ["Hi" => "Hello", "hello" => "hi"]);
// Output: Hello all, I said hi

O "Hi" torna-se "Hello", mas esse novo "Hello" não é transformado em "hi" pela segunda regra — a substituição não é recursiva. Isso torna strtr() seguro para trocar dois valores simultaneamente (por exemplo "yes" <-> "no"), algo que str_replace() não consegue fazer em uma única chamada.

A correspondência mais longa vence

Quando duas chaves podem corresponder na mesma posição, strtr() sempre prefere a mais longa:

<?php

echo strtr("a b c", ["a b" => "X", "a" => "Y"]);
// Output: X c

Mesmo que "a" apareça primeiro no array, a chave mais longa "a b" corresponde nessa posição e tem prioridade. A ordem do array não importa — apenas o comprimento da chave importa.

Forma com três argumentos: tradução caractere por caractere

A forma com três argumentos mapeia caracteres individuais. $from e $to devem ter o mesmo comprimento; cada caractere em $from é substituído pelo caractere na mesma posição em $to.

<?php

echo strtr("Hello World", "lo", "LO");
// Output: HeLLO WOrLd

Cada l torna-se L e cada o torna-se O. Se $from for maior que $to, os caracteres extras são ignorados. Esta forma é útil para trocas simples semelhantes a cifras ou normalização de caracteres, mas só pode substituir caracteres individuais — use a forma com array quando precisar substituir substrings com múltiplos caracteres.

strtr() vs str_replace()

Ambas as funções substituem texto, mas se comportam de maneira diferente:

• strtr() funciona em uma única passagem não recursiva e resolve conflitos pela correspondência mais longa. O texto substituído nunca é reanalisado.
• str_replace() aplica suas regras sequencialmente, então uma substituição anterior pode ser correspondida novamente por uma posterior. Também diferencia maiúsculas de minúsculas (use str_ireplace() para substituição sem distinção de maiúsculas e minúsculas).

Use strtr() quando tiver um mapa fixo de trocas que devem ocorrer exatamente uma vez — escape, transliteração ou trocas bidirecionais. Para substituição baseada em padrões, use preg_replace() em vez disso.

Conclusão

A função strtr() fornece uma maneira eficiente de traduzir substrings em PHP. Ela suporta tanto mapeamento baseado em array quanto tradução caractere por caractere via a forma com três argumentos. Como opera em uma única passagem usando a lógica de correspondência mais longa primeiro, é bem adequada para trocas pontuais e geralmente é mais rápida do que chamadas encadeadas de str_replace(). Entender as regras de passagem única e correspondência mais longa ajuda a escolher a ferramenta certa para cada tarefa de processamento de texto.

Prática