nedwors / pluralize
Easily and fluently pluralize content within your Laravel apps
Requires
- php: ^8.0|^8.1|^8.2
- illuminate/support: ^8.0|^9.0|^10.0
Requires (Dev)
- orchestra/testbench: ^6.0
- phpunit/phpunit: ^9.0
README
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
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 nedwors@gmail.com instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.
Laravel Package Boilerplate
This package was generated using the Laravel Package Boilerplate.