mindtwo / native-enum
Package for using native php enums.
Installs: 6 962
Dependents: 1
Suggesters: 0
Security: 0
Stars: 21
Watchers: 6
Forks: 1
Open Issues: 0
Requires
- php: >=8.1
- illuminate/collections: ^8.0|^9.0|^10.0|^11.0
- illuminate/contracts: ^8.0|^9.0|^10.0|^11.0
- illuminate/support: ^8.0|^9.0|^10.0|^11.0
- illuminate/translation: ^8.0|^9.0|^10.0|^11.0
Requires (Dev)
- phpunit/phpunit: ^9.5.10
- squizlabs/php_codesniffer: ^3.6.2
README
Enums are an invaluable tool for any developer working with PHP. They provide a way to easily and efficiently define a set of constants that can be used throughout a project. Enums also help to make code more maintainable and scalable. For example, they can help to define a set of values that must stay consistent throughout the project, like a list of permissions or statuses. This helps ensure that the same values are used in all the relevant parts of the code and that any changes are made in one place. Additionally, enums help to reduce the amount of manual testing needed since the values are already defined. Furthermore, enums provide a way for developers to quickly check for valid values, making it easier to spot errors in code and ensure that the application behaves as expected. Finally, enums are strongly typed, meaning that they can help to ensure that the correct type of data is used in each part of the application, which can help to improve overall code quality.
Inspired by the package BenSampo/laravel-enum this one uses the new native enums classes in PHP. The native functions are extended to work easily ams seamlessly with them in Laravel-based systems.
Everyone is welcome to contribute.
Enojy the Package!
Overview
Install
Installing the PHP Composer Package
Laravel Native PHP 8.1 Enums is a powerful package that can help you construct and maintain robust and scalable Laravel-based systems.
Requirements
- Laravel 9 or higher
- PHP 8.1 or higher
Composer install
Before you begin, you'll need to make sure you have the listed requirements and Composer installed on your system. You can find instructions for doing so here.
Once you have Composer installed, you can install "Laravel Native PHP 8.1 Enums" by running the following command from your project directory:
composer require mindtwo/native-enum
After the installation is complete, you'll now be ready to start using native enums in your project. Have fun!
Create enum
Artisan command
You can use the following Artisan command to generate a new native enum class in your project:
// Default: php artisan make:enum UserRole // Localized: php artisan make:enum UserRole --localized
Manual enum creation
You can also create a new native enum manually. The structure should look like this:
namespace App\Enums; enum UserRole: int { use BaseEnum; case ADMIN = 10; case CUSTOMER = 50; }
Usage
Base usage
UserRole::getRandomValue(); UserRole::getRandomName(); UserRole::getRandomInstance(); UserRole::asSelectArray(); UserRole::asArray(); UserRole::getValues(); UserRole::getNames(); UserRole::hasValue(50); UserRole::hasName('ADMIN');
Get specific enum values
UserRole::getValues('ADMIN'); UserRole::getValues(UserRole::ADMIN); UserRole::getValues([UserRole::ADMIN]); UserRole::getValues('CUSTOMER'); UserRole::getValues(UserRole::CUSTOMER); UserRole::getValues([UserRole::CUSTOMER]);
Get specific enum names
UserRole::getNames(10); UserRole::getNames(50); UserRole::getNames([10,50]);
Use static calls to get the primitive value
UserRole::ADMIN(); // 10 UserRole::CUSTOMER(); // 50
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.
use mindtwo\NativeEnum\Rules\EnumValue; public function store(Request $request) { $this->validate($request, [ 'user_role' => ['required', new EnumValue(UserRole::class)], ]); }
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.
new EnumValue(UserRole::class, false) // Turn off strict type checking.
Enum name
You can also validate on names using the EnumName
rule. This is useful if you're taking the enum name as a URL parameter for sorting or filtering for example.
use mindtwo\NativeEnum\Rules\EnumKey; public function store(Request $request) { $this->validate($request, [ 'user_role' => ['required', new EnumName(UserRole::class)], ]); }
Enum instance
Additionally you can validate that a parameter is an instance of a given enum.
use mindtwo\NativeEnum\Rules\Enum; public function store(Request $request) { $this->validate($request, [ 'user_role' => ['required', new Enum(UserRole::class)], ]); }
Localized enum
The Enum has to implement the LocalizedEnum
interface:
namespace App\Enums; enum UserRole: int implements LocalizedEnum { use BaseEnum; case ADMIN = 10; case CUSTOMER = 50; }
Translation files can be placed here lang/en/enums.php
like:
use \App\Enums; return [ Enums\UserRole::class => [ Enums\UserRole::ADMIN->name => 'Administrator', Enums\UserRole::CUSTOMER->name => 'Customer', ], ];
To get a translated name of a selected enum value:
Enums\UserRole::ADMIN->name(); // Returns "Administrator"
Change log
Please see CHANGELOG for more information on what has changed recently.
Testing
$ composer test
Contributing
Please see CONTRIBUTING and CODE_OF_CONDUCT for details.
Security
If you discover any security related issues, please email info@mindtwo.de instead of using the issue tracker.
Credits
License
The MIT License (MIT). Please see License File for more information.