strtr
Replaces characters or whole substrings in a string using a translation table or two character maps.
strtr(string $string, string $from, string $to): string
strtr(string $string, array $replace_pairs): string- Added in PHP 4.0
Parameters
| Parameter | Type | Description |
|---|---|---|
$string | string | The string being translated. |
$from | string | Three-argument form: the characters to translate from. Compared byte by byte against to. |
$to | string | Three-argument form: the characters to translate to. If from and to differ in length, the extra characters of the longer one are ignored. |
$replace_pairs | array | Two-argument form: an array in the form ['from' => 'to', ...] whose keys are substrings to replace with their values. |
Return value
stringThe translated string.
Errors
Emits E_WARNING when the replace_pairs array contains an empty string key.
Changelog
- PHP 8.0.0An E_WARNING is now raised if replace_pairs contains an empty string as a key. Previously this was silently ignored.
strtr has two completely different modes. With three string arguments it maps single bytes: every byte found in from becomes the byte at the same index in to. With an array it replaces whole substrings, trying the longest key first and never re-scanning text it has already written.
When to reach for it
The array form is the right tool for template placeholders and for any replacement set where the outputs could match the inputs. str_replace applies its pairs sequentially, so swapping a for b and b for a ends with everything as a; strtr does it in a single pass and gets the swap right. It is also the honest way to escape a set of characters that map to different sequences.
What trips people up
The three-argument form works on bytes, so it corrupts UTF-8 the moment you feed it a multibyte character. Use the array form for anything beyond ASCII.
An empty string key raises a warning in PHP 8 and is ignored. And when several keys match at the same position, length wins over array order — a shorter key that appears first in the array will not be preferred.
Example
When to use it
- Fill {placeholder} tokens in a message template in one pass.
- Swap two characters or two words without the second replacement undoing the first.
- Escape a small fixed set of characters into different multi-character sequences.
- Transliterate a fixed ASCII character map, such as digits to their leetspeak equivalents.
Frequently asked questions
What is the difference between strtr and str_replace?
strtr with an array does all replacements in one left-to-right pass and never rescans replaced text, while str_replace applies each pair in sequence over the whole string. That makes strtr correct for swaps and for escaping, and str_replace correct when you deliberately want cascading replacements.
Which key wins when two strtr array keys match at the same spot?
The longest key wins, regardless of the order it appears in the array. So ['h' => '-', 'hello' => 'hi'] replaces 'hello' rather than just its first letter.
Can strtr handle UTF-8?
Only in the array form. The three-argument form maps single bytes and will break multibyte characters apart, so pass an array of full substrings when your text is not plain ASCII.
More examples
Swapping two values without clobbering
strtr prints 'dog cat dog' — the correct swap. str_replace prints 'cat cat cat', because it first turns every cat into dog and then turns every dog (including the new ones) back into cat. This single-pass behaviour is the main reason to choose strtr.
<?php
$input = 'cat dog cat';
echo strtr($input, ['cat' => 'dog', 'dog' => 'cat']), "\n";
echo str_replace(['cat', 'dog'], ['dog', 'cat'], $input), "\n";Escaping a fixed character set
Prints '5 < 7 && 7 > 5' and its length. Because strtr never rescans its own output, the ampersands it writes for < and > are not escaped a second time — the bug you would get from naive sequential replacement.
<?php
$map = ['&' => '&', '<' => '<', '>' => '>'];
$raw = '5 < 7 && 7 > 5';
echo strtr($raw, $map), "\n";
echo strlen(strtr($raw, $map)), "\n";
Discussion