strtr()

Introduction

The strtr() function in PHP translates substrings within a string. It is particularly useful for text processing where specific sequences need to be replaced efficiently. This article covers its syntax, behavior, and practical usage.

Understanding the strtr() function

The strtr() function supports two signatures:

Array signature

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

Here, $str is the input string and $replace is an associative array mapping substrings to their replacements. The function replaces all occurrences of the keys with their corresponding values.

Three-argument signature

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

In this form, $from and $to must be the same length. Each character in $from is mapped to the character at the same position in $to.

Important behavior: strtr() replaces substrings using a longest-match-first algorithm. This means overlapping patterns are resolved by prioritizing the longest match, and replacements are not applied recursively to the output.

Array form: replacing substrings

The most common use of strtr() is the two-argument array form. You pass an associative array that maps each substring you want to find to the value it should become.

Here strtr() replaces every "H" with "J" and every "W" with "Z". The keys can be any length, so you can map whole words just as easily as single characters:

<?php

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

Replacements are applied in a single pass

This is the behavior that trips people up. strtr() scans the string once and never re-examines text it has already replaced. So a value you insert will not be matched again by another rule:

<?php

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

The "Hi" becomes "Hello", but that new "Hello" is not then turned into "hi" by the second rule — replacement is not recursive. This makes strtr() safe for swapping two values at once (for example "yes" <-> "no"), something str_replace() cannot do in a single call.

Longest match wins

When two keys could match at the same position, strtr() always prefers the longest one:

<?php

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

Even though "a" appears first in the array, the longer key "a b" matches at that position and takes priority. Array order does not matter — only key length does.

Three-argument form: character-by-character translation

The three-argument form maps individual characters. $from and $to must be the same length; each character in $from is replaced by the character at the same position in $to.

<?php

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

Every l becomes L and every o becomes O. If $from is longer than $to, the extra characters are ignored. This form is handy for simple cipher-like swaps or normalizing characters, but it can only ever replace single characters — use the array form when you need to replace multi-character substrings.

strtr() vs str_replace()

Both functions replace text, but they behave differently:

• strtr() works in a single non-recursive pass and resolves conflicts by longest match. Replaced text is never re-scanned.
• str_replace() applies its rules sequentially, so an earlier replacement can be matched again by a later one. It is also case-sensitive (use str_ireplace() for case-insensitive replacement).

Reach for strtr() when you have a fixed map of swaps that should each happen exactly once — escaping, transliteration, or two-way swaps. For pattern-based replacement, use preg_replace() instead.

Conclusion

The strtr() function provides an efficient way to translate substrings in PHP. It supports both array-based mapping and character-by-character translation via the three-argument form. Because it operates in a single pass using longest-match-first logic, it is well suited to one-shot swaps and is often faster than chained str_replace() calls. Understanding the single-pass and longest-match rules helps you pick the right tool for each text-processing task.

Practice