Download the PHP package laraval-core-modules/service-repository without Composer

About Laravel Service Repository

This is a simple and extensible package for improving development time via service and repository for Laravel.

• Enum key value pairs as class constants
• Full-featured suite of methods
• Enum instantiation
• Flagged/Bitwise enums
• Type hinting
• Attribute casting
• Enum artisan generator
• Validation rules for passing enum key or values as input parameters
• Localization support
• Extendable via Macros

Created by Corine BOCOGA

Official Documentation

Documentation for ServiceRepository can be found on the packages.tools/testbench.

Jump To

• Guide
• Installation
• Enum Library
• Basic Usage
  • Enum definition
  • Instantiation
  • Instance Properties
  • Instance Equality
  • Type Hinting
• Flagged/Bitwise Enum
• Attribute Casting
• Migrations
• Validation
• Localization
• Customizing descriptions
• Extending the Enum Base Class
• Laravel Nova Integration
• PHPStan Integration
• Artisan Command List
• Enum Class Reference
• Stubs

Documentation for older versions

You are reading the documentation for 6.x.

• If you're using Laravel 8 please see the docs for 4.x.
• If you're using Laravel 7 please see the docs for 2.x.
• If you're using Laravel 6 or below, please see the docs for 1.x.

Please see the upgrade guide for information on how to upgrade to the latest version.

Guide

I wrote a blog post about using laravel-enum: https://corine.b.github/blog/using-service-repository-in-laravel

Installation

Requirements

• Laravel 10 or higher
• PHP 8.1 or higher

Via Composer

Enum Library

Browse and download from a list of commonly used, community contributed enums.

Enum library →

Basic Usage

Enum Definition

You can use the following Artisan command to generate a new enum class:

Now, you just need to add the possible values your enum can have as constants.

That's it! Note that because the enum values are defined as plain constants, you can simply access them like any other class constant.

Instantiation

It can be useful to instantiate enums in order to pass them between functions with the benefit of type hinting.

Additionally, it's impossible to instantiate an enum with an invalid value, therefore you can be certain that the passed value is always valid.

For convenience, enums can be instantiated in multiple ways:

If you want your IDE to autocomplete the static instantiation helpers, you can generate PHPDoc annotations through an artisan command.

By default all Enums in app/Enums will be annotated (you can change the folder by passing a path to --folder)

You can annotate a single class by specifying the class name

Instance Properties

Once you have an enum instance, you can access the key, value and description as properties.

This is particularly useful if you're passing an enum instance to a blade view.

Instance Casting

Enum instances can be cast to strings as they implement the __toString() magic method.
This also means they can be echoed in blade views, for example.

Instance Equality

You can check the equality of an instance against any value by passing it to the is method. For convenience, there is also an isNot method which is the exact reverse of the is method.

You can also check to see if the instance's value matches against an array of possible values using the in method, and use notIn to check if instance value is not in an array of values. Iterables can also be checked against.

Type Hinting

One of the benefits of enum instances is that it enables you to use type hinting, as shown below.

Flagged/Bitwise Enum

Standard enums represent a single value at a time, but flagged or bitwise enums are capable of of representing multiple values simultaneously. This makes them perfect for when you want to express multiple selections of a limited set of options. A good example of this would be user permissions where there are a limited number of possible permissions but a user can have none, some or all of them.

You can create a flagged enum using the following artisan command:

php artisan make:enum UserPermissions --flagged

Defining values

When defining values you must use powers of 2, the easiest way to do this is by using the shift left << operator like so:

Defining shortcuts

You can use the bitwise or | to set a shortcut value which represents a given set of values.

Instantiating a flagged enum

There are couple of ways to instantiate a flagged enum:

Attribute casting works in the same way as single value enums.

Empty flagged enums

Flagged enums can contain no value at all. Every flagged enum has a pre-defined constant of None which is comparable to 0.

Flagged enum methods

In addition to the standard enum methods, there are a suite of helpful methods available on flagged enums.

Note: Anywhere where a static property is passed, you can also pass an enum instance.

setFlags(array $flags): Enum

Set the flags for the enum to the given array of flags.

addFlag($flag): Enum

Add the given flag to the enum

addFlags(array $flags): Enum

Add the given flags to the enum

addAllFlags(): Enum

Add all flags to the enum

removeFlag($flag): Enum

Remove the given flag from the enum

removeFlags(array $flags): Enum

Remove the given flags from the enum

removeAllFlags(): Enum

Remove all flags from the enum

hasFlag($flag): bool

Check if the enum has the specified flag.

hasFlags(array $flags): bool

Check if the enum has all of the specified flags.

notHasFlag($flag): bool

Check if the enum does not have the specified flag.

notHasFlags(array $flags): bool

Check if the enum doesn't have any of the specified flags.

getFlags(): Enum[]

Return the flags as an array of instances.

hasMultipleFlags(): bool

Check if there are multiple flags set on the enum.

getBitmask(): int

Get the bitmask for the enum.

Flagged enums in Eloquent queries

To use flagged enums directly in your Eloquent queries, you may use the QueriesFlaggedEnums trait on your model which provides you with the following methods:

hasFlag($column, $flag): Builder

notHasFlag($column, $flag): Builder

hasAllFlags($column, $flags): Builder

hasAnyFlags($column, $flags): Builder

Attribute Casting

You may cast model attributes to enums using Laravel's built in custom casting. This will cast the attribute to an enum instance when getting and back to the enum value when setting. Since Enum::class implements the Castable contract, you just need to specify the classname of the enum:

Now, when you access the user_type attribute of your Example model, the underlying value will be returned as a UserType enum.

Review the methods and properties available on enum instances to get the most out of attribute casting.

You can set the value by either passing the enum value or another enum instance.

Customising $model->toArray() behaviour

When using toArray (or returning model/models from your controller as a response) Laravel will call the toArray method on the enum instance.

By default, this will return only the value in its native type. You may want to also have access to the other properties (key, description), for example to return to javascript app.

To customise this behaviour, you can override the toArray method on the enum instance.

Casting underlying native types

Many databases return everything as strings (for example, an integer may be returned as the string '1'). To reduce friction for users of the library, we use type coercion to figure out the intended value. If you'd prefer to control this, you can override the parseDatabase static method on your enum class:

Returning null from the parseDatabase method will cause the attribute on the model to also be null. This can be useful if your database stores inconsistent blank values such as empty strings instead of NULL.

Model Annotation

If you're casting attributes on your model to enums, the laravel-ide-helper package can be used to automatically generate property docblocks for you.

Migrations

Recommended

Because enums enforce consistency at the code level it's not necessary to do so again at the database level, therefore the recommended type for database columns is string or int depending on your enum values. This means you can add/remove enum values in your code without worrying about your database layer.

Using enum column type

Alternatively you may use Enum classes in your migrations to define enum columns. The enum values must be defined as strings.

Validation

Array Validation

Enum value

You may validate that an enum value passed to a controller is a valid value for a given enum by using the EnumValue rule.

By default, type checking is set to strict, but you can bypass this by passing false to the optional second parameter of the EnumValue class.

Enum key

You can also validate on keys using the EnumKey rule. This is useful if you're taking the enum key as a URL parameter for sorting or filtering for example.

Enum instance

Additionally you can validate that a parameter is an instance of a given enum.

Pipe Validation

You can also use the 'pipe' syntax for rules.

enum_value_:enumclass,[strict]
enum_key_:enumclass
enum_:enumclass

Localization

Validation messages

Run the following command to publish the language files to your resources/lang folder.

Enum descriptions

You can translate the strings returned by the getDescription method using Laravel's built-in localization features.

Add a new enums.php keys file for each of your supported languages. In this example there is one for English and one for Spanish.

Now, you just need to make sure that your enum implements the LocalizedEnum interface as demonstrated below:

The getDescription method will now look for the value in your localization files. If a value doesn't exist for a given key, the default description is returned instead.

Customizing enum class description

If you'd like to return a custom description for your enum class, add a Description attribute to your Enum class:

Calling UserType::getClassDescription() now returns List of available User types instead of User type.

You may also override the getClassDescription method on the base Enum class if you wish to have more control of the description.

Customizing value descriptions

If you'd like to return a custom description for your enum values, add a Description attribute to your Enum constants:

Calling UserType::SuperAdministrator()->description now returns Super admin instead of Super administrator.

You may also override the getDescription method on the base Enum class if you wish to have more control of the description.

Extending the Enum Base Class

The Enum base class implements the Laravel Macroable trait, meaning it's easy to extend it with your own functions. If you have a function that you often add to each of your enums, you can use a macro.

Let's say we want to be able to get a flipped version of the enum asArray method, we can do this using:

Now, on each of my enums, I can call it using UserType::asFlippedArray().

It's best to register the macro inside a service providers' boot method.

Laravel Nova Integration

Use the nova-enum-field package by Simple Squid to easily create fields for your Enums in Nova. See their readme for usage.

PHPStan integration

If you are using PHPStan for static analysis, you can enable the extension for proper recognition of the magic instantiation methods.

Add the following to your projects phpstan.neon includes:

Artisan Command List

php artisan make:service-repository
Create a new enum class. Pass --flagged as an option to create a flagged enum.
Find out more

php artisan enum:annotate
Generate DocBlock annotations for enum classes.
Find out more

Enum Class Reference

static getKeys(mixed $values = null): array

Returns an array of all or a custom set of the keys for an enum.

static getValues(mixed $keys = null): array

Returns an array of all or a custom set of the values for an enum.

static getKey(mixed $value): string

Returns the key for the given enum value.

static getValue(string $key): mixed

Returns the value for the given enum key.

static hasKey(string $key): bool

Check if the enum contains a given key.

static hasValue(mixed $value, bool $strict = true): bool

Check if the enum contains a given value.

static getClassDescription(): string

Returns the class name in sentence case for the enum class. It's possible to customize the description if the guessed description is not appropriate.

static getDescription(mixed $value): string

Returns the key in sentence case for the enum value. It's possible to customize the description if the guessed description is not appropriate.

static getRandomKey(): string

Returns a random key from the enum. Useful for factories.

static getRandomValue(): mixed

Returns a random value from the enum. Useful for factories.

static getRandomInstance(): mixed

Returns a random instance of the enum. Useful for factories.

static asArray(): array

Returns the enum key value pairs as an associative array.

static asSelectArray(): array

Returns the enum for use in a select as value => description.

static fromValue(mixed $enumValue): Enum

Returns an instance of the called enum. Read more about enum instantiation.

static getInstances(): array

Returns an array of all possible instances of the called enum, keyed by the constant names.

static coerce(mixed $enumKeyOrValue): ?Enum

Attempt to instantiate a new Enum using the given key or value. Returns null if the Enum cannot be instantiated.

Modules

Run the following command to publish the stub files to the Modules folder in the root of your application.

Ignoring errors

Ignoring a specific error can be done either with a php comment or in the configuration file:

When ignoring errors in PHPStan's configuration file, they are ignored by writing a regex based on error messages:

Baseline file

In older codebases it might be hard to spend the time fixing all the code to pass a high PHPStan Level.

To get around this a baseline file can be generated. The baseline file will create a configuration file with all of the current errors, so new code can be written following a higher standard than the old code. (PHPStan Docs)

Rules

A list of configurable rules specific to Laravel can be found here.

Features

A list of Larastan features can be found here.

Custom PHPDoc types

A list of PHPDoc types specific to Larastan can be found here.

Custom PHPStan config parameters

A list of custom config parameters that you can use in your PHPStan config file can be found here.

Errors To Ignore

Some parts of Laravel are currently too magical for Larastan/PHPStan to understand. We listed common errors to ignore, add them as needed

👊🏻 Contributing

Thank you for considering contributing to Larastan. All the contribution guidelines are mentioned here.

You can have a look at the @can__vural.

Code of Conduct

In order to ensure that the community is welcoming to all, please review and abide by the Code of Conduct.

License

Testbench is open-sourced software licensed under the MIT license.