str_increment
Returns the next value of an alphanumeric string, carrying over like a spreadsheet column.
str_increment(string $string): string- Added in PHP 8.3
Parameters
| Parameter | Type | Description |
|---|---|---|
$string | string | The alphanumeric ASCII string to increment. |
Return value
stringThe incremented alphanumeric ASCII string.
Errors
Throws a ValueError if the string is empty or is not an alphanumeric ASCII string.
str_increment is the explicit form of PHP's long-standing string increment: 'AB' becomes 'AC', 'AZ' becomes 'BA', 'ZZ' becomes 'AAA'. Since PHP 8.3 using ++ on a non-numeric string is deprecated, so this function is the way forward.
When to reach for it
Use it wherever a sequence of short alphanumeric codes needs a successor: spreadsheet column headers, batch or lot numbers, seat and shelf labels, human-readable IDs that should stay compact. It is also useful in tests, where you need a stream of distinct short strings without maintaining a counter and formatting it.
What trips people up
Each character position keeps its own alphabet. A digit rolls within 0-9, a lowercase letter within a-z, an uppercase letter within A-Z, and a carry propagates left. That means 'a9' becomes 'b0' but '9z' becomes '10a' — the string grows when the leftmost character overflows, so the result is not always the same length as the input.
Any character outside [A-Za-z0-9], including a hyphen or space, throws a ValueError. If your codes have a prefix like INV-, split it off, increment the alphanumeric tail, and reassemble.
Example
When to use it
- Generate the next spreadsheet column label after Z, AA, AB
- Produce sequential batch or lot codes without an integer counter
- Create distinct short identifiers in a test fixture loop
- Advance a shelf or seat label such as A9 to B0
Frequently asked questions
What is the difference between str_increment and the ++ operator?
They implement the same algorithm, but ++ on a non-numeric string is deprecated as of PHP 8.3 and str_increment is the explicit replacement. str_increment also throws a ValueError on invalid input instead of failing silently.
Why did my two-character code become three characters?
Because the leftmost character overflowed its alphabet and carried: ZZ becomes AAA, 99 becomes 100. Pad or validate the result if it must fit a fixed-width field.
Can str_increment handle strings with dashes or underscores?
No, it throws a ValueError for any non-alphanumeric ASCII character. Split the prefix off, increment the alphanumeric part, and join them back together.
More examples
Generating spreadsheet column labels
The output runs A through Z and then rolls over to AA, AB, AC, AD exactly as a spreadsheet does. The carry from Z to AA is handled for you, which is the whole reason not to hand-roll this with chr() and ord().
<?php
$col = 'A';
$labels = [];
for ($i = 0; $i < 30; $i++) {
$labels[] = $col;
$col = str_increment($col);
}
echo implode(' ', $labels), "\n";
echo 'next after last: ', $col, "\n";Incrementing a code that has a prefix
The hyphen would throw a ValueError, so the prefix is split off and only the alphanumeric tail is incremented. The output shows the tail advancing 0A9, 0B0, 0B1, 0B2 — note that the digit position rolls within 0-9 while the letter position rolls within A-Z, independently.
<?php
function nextInvoice(string $id): string {
[$prefix, $tail] = explode('-', $id, 2);
return $prefix . '-' . str_increment($tail);
}
$id = 'INV-0A8';
for ($i = 0; $i < 4; $i++) {
echo $id = nextInvoice($id), "\n";
}
Discussion