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:

        
 1$formatter = new NumberFormatter(locale: 'en', style: NumberFormatter::ORDINAL);
 2 
 3$formatter->format(1); // 1st
 4$formatter->format(2); // 2nd
 5$formatter->format(3); // 3rd
 6 
 7$formatter->format(10); // 10th
 8$formatter->format(101); // 101st
 9$formatter->format(105); // 105th
10 
11$formatter->format(1_000_200); // 1,000,200th
12$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:

        
 1use Illuminate\Support\Number;
 2 
 3Number::ordinal(1); // 1st
 4Number::ordinal(2); // 2nd
 5Number::ordinal(3); // 3rd
 6 
 7Number::ordinal(10); // 10th
 8Number::ordinal(101); // 101st
 9Number::ordinal(105); // 105th
10 
11Number::ordinal(1_000_200); // 1,000,200th
12Number::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:

        
1use Illuminate\Support\Number;
2 
3Number::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:

        
1use Illuminate\Support\Number;
2 
3Number::useLocale('fr_FR');
4Number::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:

        
 1$formatter = new NumberFormatter(locale: 'en', style: NumberFormatter::SPELLOUT);
 2 
 3$formatter->setTextAttribute(
 4    attribute: NumberFormatter::DEFAULT_RULESET,
 5    value: '%spellout-ordinal',
 6);
 7 
 8$formatter->format(1); // first
 9$formatter->format(2); // second
10$formatter->format(3); // third
11 
12$formatter->format(10); // tenth
13$formatter->format(101); // one hundred first
14$formatter->format(105); // one hundred fifth
15 
16$formatter->format(1_000_200); // one million two hundreth
17$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:

        
 1use Illuminate\Support\Number;
 2 
 3Number::spellOrdinal(1); // first
 4Number::spellOrdinal(2); // second
 5Number::spellOrdinal(3); // third
 6 
 7Number::spellOrdinal(10); // tenth
 8Number::spellOrdinal(101); // one hundred first
 9Number::spellOrdinal(105); // one hundred fifth
10 
11Number::spellOrdinal(1_000_200); // one million two hundreth
12Number::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:

        
1use Illuminate\Support\Number;
2 
3Number::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:

        
1use Illuminate\Support\Number;
2 
3Number::useLocale('fr_FR');
4Number::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:

        
 1$formatter = new NumberFormatter('en', NumberFormatter::SPELLOUT);
 2 
 3$formatter->setTextAttribute(
 4    attribute: NumberFormatter::DEFAULT_RULESET,
 5    value: '%spellout-ordinal-verbose',
 6);
 7 
 8$formatter->format(10); // tenth
 9$formatter->format(101); // one hundred and first
10$formatter->format(105); // one hundred and fifth
11 
12$formatter->format(1_000_200); // one million, two hundreth
13$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 below.

Keep on building awesome stuff! 🚀