Formatting and Spelling Ordinal Numbers in PHP and Laravel

Introduction

There may be times when you want to convert numbers to ordinal numbers in your PHP and Laravel applications. For example, you might want to display a user's ranking in a leaderboard and show the rank as "1st", "2nd", "3rd", rather than "1", "2", "3".

You may also want to spell out the ordinal numbers in words, for example, "1st" to "first", "2nd" to "second", "3rd" to "third", etc.

In this article, we'll look at how to convert numbers to ordinal numbers in PHP and Laravel. We'll also look at how to spell out ordinal numbers in words. I'll provide examples for use in both Laravel and non-Laravel PHP applications.

Pre-requisites

Before we get started, it's worth noting that the examples covered in this article require the intl PHP extension to be installed.

Convert Numbers to Ordinal Numbers in PHP

Let's take a look at how to convert numbers to ordinal numbers in PHP (e.g., "1" to "1st", "105" to "105th", etc.).

To do this, we can use the NumberFormatter class like so:

$formatter = new NumberFormatter(
    locale: 'en',
    style: NumberFormatter::ORDINAL,
);

$formatter->format(1); // 1st
$formatter->format(2); // 2nd
$formatter->format(3); // 3rd

$formatter->format(10); // 10th
$formatter->format(101); // 101st
$formatter->format(105); // 105th

$formatter->format(1_000_200); // 1,000,200th
$formatter->format(-1_000_200); // -1,000,200th

As we can see in the example above, I've passed a locale of en as that's most suitable for me. But you may want to use a different locale depending on your application.

To convert the number to an ordinal number, we need to set the style to NumberFormatter::ORDINAL.

Convert Numbers to Ordinal Numbers in Laravel

If you need to convert the numbers to ordinal numbers in Laravel, you can use the handy Illuminate\Support\Number class which has an ordinal method:

use Illuminate\Support\Number;

Number::ordinal(1); // 1st
Number::ordinal(2); // 2nd
Number::ordinal(3); // 3rd

Number::ordinal(10); // 10th
Number::ordinal(101); // 101st
Number::ordinal(105); // 105th

Number::ordinal(1_000_200); // 1,000,200th
Number::ordinal(-1_000_200); // -1,000,200th

As we can see, we've achieved the same result as the previous example, but this time using the Illuminate\Support\Number class.

Using Different Locales

By default, the Illuminate\Support\Number class will use en as the locale for formatting numbers. However, you can change this by passing the intended locale as the second argument to the ordinal method. For example, if you want to use the fr_FR locale, you can do so like this:

use Illuminate\Support\Number;

Number::ordinal(-1_000_200, locale: 'fr_FR'); // −1 000 200e

Similarly, you can override the locale for all the method calls on the Illuminate\Support\Number class by using the use locale method. For example, if you want to use the fr_FR locale, you can do so like this:

use Illuminate\Support\Number;

Number::useLocale('fr_FR');
Number::ordinal(-1_000_200); // −1 000 200e

In the code example above, we can see that -1_000_200 is formatted as −1 000 200e in the French locale.

Spelling Ordinal Numbers in PHP

There may also be times when you want to spell out the ordinal numbers in words. For example, "1st" to "first", "2nd" to "second", "3rd" to "third", etc.

Let's take a look at how we can do this using the NumberFormatter class:

$formatter = new NumberFormatter(locale: 'en', style: NumberFormatter::SPELLOUT);

$formatter->setTextAttribute(
    attribute: NumberFormatter::DEFAULT_RULESET,
    value: '%spellout-ordinal',
);

$formatter->format(1); // first
$formatter->format(2); // second
$formatter->format(3); // third

$formatter->format(10); // tenth
$formatter->format(101); // one hundred first
$formatter->format(105); // one hundred fifth

$formatter->format(1_000_200); // one million two hundreth
$formatter->format(-1_000_200); // minus one million two hundreth

As we can see in the code example above, we've first started by creating a new NumberFormatter instance and passing the locale and style as NumberFormatter::SPELLOUT. We've also specified that we want to spell out the ordinal numbers.

Then, we can use the format method to convert the numbers to ordinal numbers in words.

Spelling Ordinal Numbers in Laravel

Similar to the ordinal method on the Illuminate\Support\Number class, Laravel also provides a spellOrdinal method to spell out the ordinal numbers in words.

We can use it like this:

use Illuminate\Support\Number;

Number::spellOrdinal(1); // first
Number::spellOrdinal(2); // second
Number::spellOrdinal(3); // third

Number::spellOrdinal(10); // tenth
Number::spellOrdinal(101); // one hundred first
Number::spellOrdinal(105); // one hundred fifth

Number::spellOrdinal(1_000_200); // one million two hundreth
Number::spellOrdinal(-1_000_200); // minus one million two hundreth

Using Different Locales

As we've already discussed, the Illuminate\Support\Number class will use en as the locale for formatting numbers by default.

However, you can change this by passing the intended locale as the second argument to the spellOrdinal method. For example, if you want to use the fr_FR locale, you can do so like this:

use Illuminate\Support\Number;

Number::spellOrdinal(-1_000_200, locale: 'fr_FR'); // moins un million deux cents

Alternatively, as we've seen, we can override the locale for all the method calls on the Illuminate\Support\Number class by using the useLocale method. For example, if you want to use the fr_FR locale, you can do so like this:

use Illuminate\Support\Number;

Number::useLocale('fr_FR');
Number::spellOrdinal(-1_000_200); // moins un million deux cents

Spelling Verbose Ordinal Numbers in PHP

In the UK, we typically include the word "and" when spelling out numbers. For example, "one hundred and first", rather than "one hundred first".

As we can see in our previous examples, our results haven't included the word "and". So if we want to format our spelled-out numbers, we need to tweak our NumberFormatter instance. Rather than passing %spellout-ordinal to the setTextAttribute method, we need to pass %spellout-ordinal-verbose like so:

$formatter = new NumberFormatter('en', NumberFormatter::SPELLOUT);

$formatter->setTextAttribute(
    attribute: NumberFormatter::DEFAULT_RULESET,
    value: '%spellout-ordinal-verbose',
);

$formatter->format(10); // tenth
$formatter->format(101); // one hundred and first
$formatter->format(105); // one hundred and fifth

$formatter->format(1_000_200); // one million, two hundreth
$formatter->format(-1_000_200); // minus one million, two hundreth

As we can see in the example, "101" is returned as "one hundred and first" and "1_000_000" is returned as "one million, two hundreth".

To my knowledge, at the time of writing this article, Laravel doesn't support using this verbose approach to formatting numbers. So if you need to include the word "and", you'll need to use the NumberFormatter class rather than the Number class.

Conclusion

Hopefully, this article has provided you with a quick overview of how to convert numbers to ordinal numbers in PHP and Laravel. We've also looked at how to spell out the ordinal numbers in words.

If you enjoyed reading this post, you might be interested in checking out my 220+ page ebook "Battle Ready Laravel" which covers similar topics in more depth.

Or, you might want to check out my other 440+ page ebook "Consuming APIs in Laravel" which teaches you how to use Laravel to consume APIs from other services.

If you're interested in getting updated each time I publish a new post, feel free to sign up for my newsletter.

Keep on building awesome stuff! 🚀