307 lines
7.3 KiB
Markdown
307 lines
7.3 KiB
Markdown
# Elegant Enum implementation for Laravel
|
|
|
|
[![Latest Version on Packagist][ico-version]][link-packagist]
|
|
[![Software License][ico-license]](LICENSE.md)
|
|
[![Build Status][ico-tests]][link-tests]
|
|
[![StyleCI][ico-style]][link-style]
|
|
[![Coverage Status][ico-scrutinizer]][link-scrutinizer]
|
|
[![Quality Score][ico-code-quality]][link-code-quality]
|
|
[![Total Downloads][ico-downloads]][link-downloads]
|
|
|
|
Based on [MyCLabs PHP Enum](https://github.com/myclabs/php-enum) and implements [SplEnum](http://php.net/manual/ru/class.splenum.php) interface.
|
|
|
|
You could find documentation for base features in [PHP Enum Readme](https://github.com/myclabs/php-enum/blob/master/README.md).
|
|
|
|
Features:
|
|
|
|
- `make:enum` command
|
|
- ability to cast enum fields for Eloquent models
|
|
- labels translation via lang files
|
|
- simple validation rule
|
|
|
|
## Simple Enum Example
|
|
|
|
```php
|
|
namespace App\Enums;
|
|
|
|
use MadWeb\Enum\Enum;
|
|
|
|
/**
|
|
* @method static PostStatusEnum FOO()
|
|
* @method static PostStatusEnum BAR()
|
|
* @method static PostStatusEnum BAZ()
|
|
*/
|
|
final class PostStatusEnum extends Enum
|
|
{
|
|
const __default = self::PENDING;
|
|
|
|
const PUBLISHED = 'published';
|
|
const PENDING = 'pending';
|
|
const DRAFT = 'draft';
|
|
}
|
|
```
|
|
|
|
## Installation
|
|
|
|
For **Laravel < 7** version - use [1.0 branch](https://github.com/mad-web/laravel-enum/tree/1.0).
|
|
|
|
You can install the package via composer:
|
|
|
|
```bash
|
|
composer require mad-web/laravel-enum
|
|
```
|
|
|
|
## Usage
|
|
|
|
Make new Enum class via artisan command:
|
|
|
|
```bash
|
|
php artisan make:enum PostStatusEnum
|
|
```
|
|
|
|
to populate Enum with your own values, pass it after `name` argument:
|
|
|
|
```bash
|
|
php artisan make:enum PostStatusEnum DRAFT=draft PENDING=pending PUBLISHED=published
|
|
```
|
|
|
|
Create instance of Enum class
|
|
|
|
``` php
|
|
$status = new PostStatusEnum(PostStatusEnum::PENDING);
|
|
|
|
// or just use magic static method
|
|
$status = PostStatusEnum::PENDING();
|
|
```
|
|
|
|
Enums support native [Custom Casts](https://laravel.com/docs/7.x/eloquent-mutators#custom-casts) feature out of the box.
|
|
Specify Enum class for attribute in `$casts` array:
|
|
|
|
```php
|
|
class Post extends Model
|
|
{
|
|
protected $fillable = ['title', 'status'];
|
|
|
|
protected $casts = [
|
|
'status' => PostStatusEnum::class,
|
|
];
|
|
}
|
|
```
|
|
|
|
after that you could get and set enum field using enum classes
|
|
|
|
```php
|
|
$post = Post::first();
|
|
|
|
$status = $post->status; // PostStatusEnum
|
|
|
|
$post->status = PostStatusEnum::PENDING();
|
|
|
|
$post->save();
|
|
```
|
|
|
|
### Enum values labels (Localization)
|
|
|
|
Create `enums.php` lang file and declare labels for enum values
|
|
|
|
```php
|
|
// resources/lang/en/enums.php
|
|
|
|
return [
|
|
PostStatusEnum::class => [
|
|
PostStatusEnum::PENDING => 'Pending Label',
|
|
PostStatusEnum::PUBLISHED => 'Published Label',
|
|
PostStatusEnum::DRAFT => 'Draft Label',
|
|
],
|
|
];
|
|
```
|
|
|
|
and get a label
|
|
|
|
```php
|
|
PostStatusEnum::PENDING()->label(); // Pending Label
|
|
```
|
|
|
|
---
|
|
|
|
To override default enum lang file path, publish `laravel-enum` config
|
|
|
|
```bash
|
|
php artisan vendor:publish --provider=MadWeb\\Enum\\EnumServiceProvider
|
|
```
|
|
|
|
and change `lang_file_path` option
|
|
|
|
```php
|
|
// config/enum.php
|
|
|
|
return [
|
|
'lang_file_path' => 'custom.path.to.enums',
|
|
];
|
|
```
|
|
|
|
### Validation Rule
|
|
|
|
You may validate an enum value from a request by using the `EnumRule` class or `Enum::rule()` method.
|
|
|
|
``` php
|
|
public function store(Request $request)
|
|
{
|
|
$this->validate($request, [
|
|
'status' => ['required', new EnumRule(PostStatusEnum::class)],
|
|
]);
|
|
|
|
// OR
|
|
|
|
$this->validate($request, [
|
|
'status' => ['required', PostStatusEnum::rule()],
|
|
]);
|
|
}
|
|
```
|
|
|
|
If you want to validate an enum key instead of an enum value you can by specifying you want to validate against the key
|
|
instead of the value.
|
|
|
|
``` php
|
|
public function store(Request $request)
|
|
{
|
|
$this->validate($request, [
|
|
'status' => ['required', new EnumRule(PostStatusEnum::class, true)],
|
|
]);
|
|
|
|
// OR
|
|
|
|
$this->validate($request, [
|
|
'status' => ['required', PostStatusEnum::ruleByKey()],
|
|
]);
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
To customize validation message, add `enum` key to validation lang file
|
|
|
|
```php
|
|
// resources/lang/en/validation.php
|
|
return [
|
|
//...
|
|
'enum' => 'Custom validation message form enum attribute :attribute',
|
|
];
|
|
```
|
|
|
|
## Additional methods
|
|
|
|
### getRandomKey(): string
|
|
|
|
Returns a random key from the enum.
|
|
|
|
```php
|
|
PostStatusEnum::getRandomKey(); // Returns 'PUBLISHED` or `PENDING` or `DRAFT`
|
|
```
|
|
|
|
### getRandomValue()
|
|
|
|
Returns a random value from the enum.
|
|
|
|
```php
|
|
PostStatusEnum::getRandomValue(); // Returns 'published` or `pending` or `draft`
|
|
```
|
|
|
|
### label(): string
|
|
|
|
Returns label for the enum value object
|
|
|
|
```php
|
|
PostStatusEnum::PUBLISHED()->label(); // Returns 'published` or custom label declared in a lang file
|
|
```
|
|
|
|
### labels(): array
|
|
|
|
Returns all labels for a enum
|
|
|
|
```php
|
|
PostStatusEnum::labels(); // Returns ['published`, 'pending', 'draft'] or array of custom labels declared in a lang file
|
|
```
|
|
|
|
### is($value): bool
|
|
|
|
Checks whether the current enum value is equal to a given enum
|
|
|
|
```php
|
|
|
|
$status = PostStatusEnum::PENDING();
|
|
|
|
|
|
PostStatusEnum::PUBLISHED()->is($status); // false
|
|
|
|
PostStatusEnum::PENDING()->is($status); // true
|
|
|
|
// or
|
|
|
|
PostStatusEnum::PUBLISHED()->is($status->getValue()); // false
|
|
|
|
PostStatusEnum::PENDING()->is($status->getValue()); // true
|
|
|
|
// or check one of multiple values
|
|
|
|
$status->is([PostStatusEnum::DRAFT(), PostStatusEnum::PUBLISHED()]) // false
|
|
|
|
$status->is([PostStatusEnum::DRAFT(), PostStatusEnum::PENDING()]) // true
|
|
```
|
|
|
|
### rule(): EnumRule
|
|
|
|
Returns instance of validation rule class for the Enum
|
|
|
|
```php
|
|
PostStatusEnum::rule(); // new EnumRule(PostStatusEnum::class);
|
|
```
|
|
|
|
### getConstList(bool $include_default = false): array
|
|
|
|
Returns all consts (possible values) as an array according to [SplEnum::getConstList](http://php.net/manual/en/splenum.getconstlist.php)
|
|
|
|
## Changelog
|
|
|
|
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
|
|
|
|
## Testing
|
|
|
|
``` bash
|
|
composer test
|
|
```
|
|
|
|
## Contributing
|
|
|
|
Please see [CONTRIBUTING](CONTRIBUTING.md) and [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) for details.
|
|
|
|
## Security
|
|
|
|
If you discover any security related issues, please email madweb.dev@gmail.com instead of using the issue tracker.
|
|
|
|
## Credits
|
|
|
|
- [Mad Web](https://github.com/mad-web)
|
|
- [All Contributors](../../contributors)
|
|
|
|
## License
|
|
|
|
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
|
|
|
|
[ico-version]: https://img.shields.io/packagist/v/mad-web/laravel-enum.svg?style=flat-square
|
|
[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square
|
|
[ico-tests]: https://github.com/mad-web/laravel-enum/workflows/tests/badge.svg
|
|
[ico-style]: https://styleci.io/repos/138497948/shield
|
|
[ico-scrutinizer]: https://img.shields.io/scrutinizer/coverage/g/mad-web/laravel-enum.svg?style=flat-square
|
|
[ico-code-quality]: https://img.shields.io/scrutinizer/g/mad-web/laravel-enum.svg?style=flat-square
|
|
[ico-downloads]: https://img.shields.io/packagist/dt/mad-web/laravel-enum.svg?style=flat-square
|
|
|
|
[link-packagist]: https://packagist.org/packages/mad-web/laravel-enum
|
|
[link-tests]: https://github.com/mad-web/laravel-enum/actions
|
|
[link-style]: https://styleci.io/repos/138497948
|
|
[link-scrutinizer]: https://scrutinizer-ci.com/g/mad-web/laravel-enum/code-structure
|
|
[link-code-quality]: https://scrutinizer-ci.com/g/mad-web/laravel-enum
|
|
[link-downloads]: https://packagist.org/packages/mad-web/laravel-enum
|
|
[link-author]: https://github.com/mad-web
|
|
[link-contributors]: ../../contributors
|