Pluralize - A Laravel string helper

A Laravel package that provides null-safe, meaningful pluralization of strings.

Go from this...

@if($pizzas)

{{ $pizzas->count() }} {{ Str::plural('Pizza', $pizzas->count()) }}

@else

-

@endif

// 2 Pizzas
// -

To this...

{{ pluralize('Pizza', $pizzas) }}

// 2 Pizzas
// -

Nice eh?

No more count($me), $me->count() or $me->total()... Just pass in your variable and have it counted for you.

No need to repeat {{ $lemons->count() }} {{ Str::plural('Lemon', $lemons->count()) }} over and over everywhere in your views. Just a unified format across your app.

No need to think anymore about whether the variable is null and what to do if so, just a clean -, or whatever you want.

The stuff of nightmares...

Call to a member function count() on null

Docs

• Installation
  • Setup
• Introduction
  • Helper vs Class
  • Usage
• Features/API
  • Pluralize
  • This
  • From
  • Or
  • As
• Configuration
  • Default Bindings
  • Specific Bindings
  • Driver

Installation

You can install the package via composer

composer require nedwors/pluralize

Setup

Minimal, if any, setup is required. The package is ready to work out of the box with sensible defaults.

The defaults are shown below. The 1st comment represents the returned string when $pizzas has a count of 10; the 2nd represents when $pizzas is null:

pluralize('Pizza', $pizzas)

// 10 Pizzas
// -

However you are free to configure these defaults, and fine tune the system further.

Introduction

Helper vs Class

This documentation's examples are based on the helper function pluralize(). However, the underlying class can be used just the same for every feature. For instance, the following are equivalent:

pluralize('Dog', $dogs, '...')

pluralize('Dog')->from($dogs)->or('...')

Pluralize::this('Dog')->from($dogs)->or('...')

Usage

The underlying class in the package implements the Stringable interface, so in your Blade views it works just by calling the helper function or class.

pluralize('Dog', $dogs)

Outside your views, do any of the following

pluralize('Dog', $dogs)() // Invoke

pluralize('Dog', $dogs)->go() // Call the go() method

(string) pluralize('Dog', $dogs) // Cast the type

Features/API

Pluralize

Pluralize has 4 main functions:

Pluralize::this(...)->from(...)->as(...)->or(...)

The pluralize() helper function has 4 parameters that map to these functions:

pluralize('this', 'from', 'or', 'as')

You'll notice that or is listed before as in the parameter list. This helps with usability for most use cases.

It can be accessed fluently too

pluralize(...)->from(...)->as(...)->or(...)

This

The singular form of the string you wish to be pluralized.

// The first argument to the helper function

pluralize('Rocket')

From

The count/total/sum you wish to pluralize the string from.

The variable you pass can be an int, an array, a Collection, a LengthAwarePaginator or a Paginator.

// The second argument to the helper function

pluralize('Rocket', $rockets)

// Or, as a method

pluralize('Rocket')->from($rockets)

By this point, it's worth noting that you are good to go. Nothing more is required for most uses.

Pluralize does provide extra features for more flexibility. These are detailed below, as well as configuration.

Or

The string to display if the count is null.

This is not required. If not provided, it will simply defer to the default -.

// The third argument to the helper function

pluralize('Rocket', $rockets, '...')

// Or, as a method

pluralize('Rocket', $rockets)->or('...')

In addition to providing a string, you can pass a Closure that will receive the pluralized form of the word.

pluralize('Rocket', $rockets)
    ->or(fn($plural) => "Oops, $plural is not defined")

// Oops, Rockets is not defined

Why would I ever write a Closure when I can just type Oops, Rockets is not defined?

It's true, it's probably unlikely. But at least the power is there if needed. For instance, perhaps you want to grab the Auth::user(), or give context with the current time.

However, the power of using a Closure really comes when configuring the package.

As

The format to display the pluralization.

This is not required. If not provided, it will simply defer to the default n items.

The most useful means is declaring this as a Closure, which is passed the plural form of the string and the count.

// The fourth argument to the helper function

pluralize('Rocket', $rockets, '...', fn($plural, $count) => "$plural: $count")

// Or, probably more usefully, as a method

pluralize('Rocket', $rockets)->as(fn($plural, $count) => "$plural: $count")

// Rockets: 10

How about if you wanted something along the lines of there are 10 Rockets? When there's 1 Rocket, you'll end up with There are 1 Rocket... Hmm. Well, the pipe operator is your friend! Simply declare the singular output to the left, the plural to the right.

pluralize('Rocket', $rockets)
    ->as(fn($plural, $count) => "There is|are $count $plural")

// There is 1 Rocket
// There are 2 Rockets

Now, you can pass a string if you really, really want to...

pluralize('Rocket', $rockets)
    ->as('Not sure how many, but you have some Rockets')

// Now sure how many, but you have some Rockets

...but this is most useful when used with your configuration.

Configuration

You can easily configure different aspects of the package. This is all done via the Pluralize class in your service provider.

Default Bindings

You can declare the default formats for use in your app by calling Pluralize::bind() with no arguments

// In your service provider's boot() method
Pluralize::bind()
    ->output(fn($plural, $count) => "$plural: $count")
    ->fallback('...')

// In your view
pluralize('Car', $cars)

// When $cars = null, ...
// When $cars = 10, Cars: 10

The default Output is n items. The default Fallback is -.

Specific Bindings

You can bind to the word you want to pluralize for specific formatting

// In your service provider's boot() method
Pluralize::bind('Hotdog')
    ->output(fn($plural, $count) => "Yum, $count hotdogs!")

// In your view
pluralize('Car', $cars) // 10 Cars
pluralize('Hotdog', $hotdogs) // Yum, 10 hotdogs!

You can set an arbitrary key to be referred to at time of render

// In your service provider's boot() method
Pluralize::bind('ye-olde')
    ->fallback(fn($plural) => "Thou hath not declared $plural")

// In your view
pluralize('Robot', null) // -
pluralize('DeLorean', null)->or('ye-olde') // Thou hath not declared DeLoreans

Driver

The package uses the Laravel Str::plural() method for pluralizing the strings passed in. You are free to use your own driver if desired. This would be especially useful for non-english languages.

Write your custom driver implementing the Pluralization interface. This defines one method, run(), which is passed the singular string and the current count. Here's the current implementation:

public function run(string $string, $count): string
{
    return Str::plural($string, $count);
}

Then set this as the desired driver in the boot() method of your service provider

Pluralize::driver(NewDriver::class)

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Sam Rowden
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Laravel Package Boilerplate

This package was generated using the Laravel Package Boilerplate.