str_decrement
Returns the previous value of an alphanumeric string, reversing PHP's string increment.
str_decrement(string $string): string- Added in PHP 8.3
Parameters
| Parameter | Type | Description |
|---|---|---|
$string | string | The alphanumeric ASCII string to decrement. |
Return value
stringThe decremented alphanumeric ASCII string.
Errors
Throws a ValueError if the string is empty, is not an alphanumeric ASCII string, or cannot be decremented any further (for example "A", "a" or "0").
See also
str_decrement is the counterpart PHP lacked for two decades. The ++ operator has always incremented strings ('az' becomes 'ba'), but -- silently did nothing. Since PHP 8.3 this function performs the true reverse, and PHP 8.3 also deprecated -- on empty and non-numeric strings, so the intent has to be explicit.
When to reach for it
Use it when you are walking backwards through a sequence of alphanumeric codes: spreadsheet columns (AA → Z), row labels, batch or lot identifiers, or short slug counters. Paired with str_increment, it gives you a bidirectional cursor over a code space without converting to and from integers.
What trips people up
Every failure mode is a ValueError, not a returned false. Passing an empty string, anything containing a hyphen, space, underscore or non-ASCII byte, or a value already at the bottom of its range throws. That last case is the one that reaches production: str_decrement('A') and str_decrement('0') both throw because there is nothing before them. Wrap loop conditions in a check or a try/catch.
Note also that a leading digit shrinks: '10' decrements to '9', so the result is not always the same length as the input.
Example
When to use it
- Step backwards through spreadsheet column labels such as AB, AA, Z
- Generate the identifier immediately before a known batch code
- Walk a range of alphanumeric SKUs in reverse for a rollback script
- Pair with str_increment to move a cursor either way over short codes
Frequently asked questions
Why does the -- operator not work on strings?
PHP's decrement operator never had string support, and since PHP 8.3 using it on a non-numeric string is deprecated. str_decrement is the explicit replacement.
What happens if I decrement "A" or "0"?
It throws a ValueError, because there is no previous value in the sequence. Catch it, or check the value before decrementing.
Does str_decrement work on strings with dashes or spaces?
No. The input must be alphanumeric ASCII only; anything else, including an empty string, throws a ValueError. Strip separators and decrement the alphanumeric part on its own.
More examples
Counting backwards safely
The loop collects five successive codes going down, and the try/catch is what stops it cleanly if the sequence reaches its floor. Note the borrow at AA: the next value drops to a single character, which is why you cannot assume the string length stays constant.
<?php
$code = 'AC';
$seen = [];
for ($i = 0; $i < 5; $i++) {
$seen[] = $code;
try {
$code = str_decrement($code);
} catch (ValueError) {
break;
}
}
echo implode(' -> ', $seen), "\n";Round-tripping with str_increment
Incrementing and then decrementing returns the original value in each case, including where a carry occurs (ZZ becomes AAA and back again). This confirms the two functions are exact inverses over the alphanumeric ASCII space, which is what makes them safe to use as a bidirectional cursor.
<?php
$codes = ['AB', 'B0', 'a1', 'ZZ'];
foreach ($codes as $c) {
$up = str_increment($c);
$back = str_decrement($up);
printf("%-4s ++ => %-4s -- => %-4s same:%s\n", $c, $up, $back, var_export($c === $back, true));
}
Discussion