PHP str_decrement() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
String

Definition

In PHP 8.3 and later, str_decrement() moves an alphanumeric string one step back.

It is the opposite of str_increment(). For example, "c" becomes "b" and "AB" becomes "AA".

Syntax

Call str_decrement() with the values you need. Start with this line.

PHP
$prev = str_decrement($label);
CallWhat it does
str_decrement("c")Returns "b".
str_decrement("BA")Returns "AZ".

Only letters a-z, A-Z, and digits 0-9 are allowed. Strings like "a", "A", and "0" cannot be decremented.

Library declarations
PHP
str_decrement(string $string): string

Parameters

ParameterDescription
stringRequired. A non-empty alphanumeric string.

Return Value

Return ValueDescription
stringThe previous string in the sequence.

PHP Examples

Example 1 — Step Back One Letter

Each call moves the string one step backward.

PHP
<?php
echo str_decrement("c"), PHP_EOL;
echo str_decrement("Az"), PHP_EOL;

How It Works

  1. Pass a letter. c is the third letter.
  2. Get the previous one. The result is b.
  3. Case is kept. Az becomes Ay.
  4. Only the last letter changes. Unless a carry is needed.

Example 2 — Carry and Lowest Value

Going below the lowest value throws an error.

PHP
<?php
echo str_decrement("BA"), PHP_EOL;
echo str_decrement("AA"), PHP_EOL;

try {
    echo str_decrement("A");
} catch (ValueError $e) {
    echo "Cannot go below A", PHP_EOL;
}

How It Works

  1. Borrow from the left. BA becomes AZ.
  2. Drop a leading letter. AA becomes Z.
  3. Try the lowest value. A has nothing before it.
  4. Catch the ValueError. Show a friendly message.

Example 3 — Count Down Spreadsheet Columns

Use a loop to walk backward through column names.

PHP
<?php
$col = "AB";
$cols = [];

for ($i = 0; $i < 4; $i++) {
    $cols[] = $col;
    $col = str_decrement($col);
}

echo implode(", ", $cols), PHP_EOL;

How It Works

  1. Start at AB. That is column 28 in a spreadsheet.
  2. Save each name. Add it to the array before stepping back.
  3. Call str_decrement(). It moves one column back.
  4. Join the names. The list shows the walk backward.

Frequently Asked Questions

str_decrement() returns the previous string in an alphanumeric sequence, such as "c" to "b" or "BA" to "AZ".
str_decrement(string $string): string. It takes one non-empty alphanumeric string.
PHP 8.3. It does not exist in earlier versions.
It throws a ValueError for an empty string, a string with other characters, or a lowest value such as "A", "a", or "0".
str_increment(). It moves the string one step forward, such as "Az" to "Ba".

Next: str_ends_with()

str_ends_with() checks whether a string ends with a given text.

str_ends_with() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful