diff --git a/changelog.md b/changelog.md index 366f4dc..b69d446 100644 --- a/changelog.md +++ b/changelog.md @@ -2,46 +2,46 @@ All notable changes to `Enum` will be documented in this file. -## Version 0.0.1 -### Initial release - -## Version 0.0.2 +## **Version 2.1.0** -### - Add +### Added -- Enum cast in Models +- Full unit tests with 100% coverage +- A laravel command to generate an Enum ``php artisan make:enum` +- examples and a full, readme doc - usage: - Put this in your model +### Changed - use CastsEnums; +- Code refactoring for most of the code +- Removed unused code parts +- Set requirements for unit test to laravel 7 +- translations are in php files - protected $enumCasts = [ - 'status' => OrderStatus::class // This is a class that extends \Kwaadpepper\Enum\BaseEnum - ]; +### Fixed -## Version 0.1.0 +- An enum used as in a route will now provoque a 404 code instead of generating null enum +- CheckEnumRule nows works properly and has unit tests -### - Changed +## **Version 2.0.0** -- toArray Method now returns an array of BaseEnums - this is because php numeric string array indexes to int, this would break - origin enum values +### Changed -## Version 0.1.1 +- Now if you are using enums in laravel, you have to extend from `BaseEnumRoutable` instead of `BaseEnum`. This will allow for enum to be used in routes as a parameter getting them as a controller parameter with implicit binding. +- All laravel dependencies have been removed, this allows enum to be used in another project type. The project is now dependency free. -### Fixed +## **Version 0.1.4** -- Fixed performances issue on toValues and toLabels +### Added -## Version 0.1.2 +- Validation rule EnumIsValidRule, the constructor needs a BaseEnum class + eg: new EnumIsValidRule(ArcadiaMailType::class) -### Changed +### Fixed -- Changed toJson to output array with label and value +- Unit tests with 0.1.2 changes -## Version 0.1.3 +## **Version 0.1.3** ### Added @@ -51,3 +51,42 @@ All notable changes to `Enum` will be documented in this file. ### Fixed - Unit tests with 0.1.2 changes + +## **Version 0.1.2** + +### Changed + +- Changed toJson to output array with label and value + +## **Version 0.1.1** + +### Fixed + +- Fixed performances issue on toValues and toLabels + +## **Version 0.1.0** + +### - Changed + +- toArray Method now returns an array of BaseEnums + this is because php numeric string array indexes to int, this would break + origin enum values + +## **Version 0.0.2** + +### - Add + +- Enum cast in Models + + usage: + Put this in your model + + use CastsEnums; + + protected $enumCasts = [ + 'status' => OrderStatus::class // This is a class that extends \Kwaadpepper\Enum\BaseEnum + ]; + +## **Version 0.0.1** + +### Initial release diff --git a/examples/BasicEnum.php b/examples/BasicEnum.php new file mode 100644 index 0000000..afccb31 --- /dev/null +++ b/examples/BasicEnum.php @@ -0,0 +1,16 @@ + 1, + 'mon' => 1 << 1, + 'tue' => 1 << 2, + 'wed' => 1 << 3, + 'thu' => 1 << 4, + 'fri' => 1 << 5, + 'sat' => 1 << 6, + 'sun' => 1 << 7, + ]; + } + + protected static function labels(): array + { + return [ + 'none' => 'None', + 'mon' => 'Monday', + 'tue' => 'Tuesday', + 'wed' => 'Wednesday', + 'thu' => 'Thursday', + 'fri' => 'Friday', + 'sat' => 'Saturday', + 'sun' => 'Sunday' + ]; + } + + public function __toString(): string + { + return (string)$this->label; + } + + /** + * Checks if days contain this day + * + * @param int $days + * @return boolean + */ + public function has(int $days) + { + return (bool)($this->value & $days); + } +} diff --git a/readme.md b/readme.md index 7b54eed..752b305 100644 --- a/readme.md +++ b/readme.md @@ -4,7 +4,10 @@ [![Total Downloads][ico-downloads]][link-downloads] ![GitHub Workflow Status](https://img.shields.io/github/workflow/status/Kwaadpepper/enum/PHP%20Composer?style=flat-square) -This is where your description should go. Take a look at [contributing.md](contributing.md) to see a to do list. +This package goal is to provide a complete solution to lack a long time php weakness : it do not have any `enum` support. +This will change with [**php 8 enums proposition**](https://php.watch/versions/8.1/enums). In the mean time we still a support for this allowing us to generate generic and extendable applications (instead of have singletons sql tables..). + +You will be able to use enums in any project using a simple definition, take a look at example [Basic](examples/BasicEnum.php) or a [more sophisticated Example](examples/Days.php) ## Installation @@ -14,26 +17,110 @@ Via Composer $ composer require kwaadpepper/enum ``` +--- + ## Usage +**All enum have two properties : `label` and `value`, only value has to be unique. Each enum can have multiple options all written on class comment as static methods, these have to be unique !** + +- On Any project, take a look on [examples](examples) to create an enum class. + +1. **Invoke an enum value** + ``` php + Days::mon() + ``` + +2. **Compare enums** + ``` php + Days::mon()->equals(Days::tue()) // false + Days::mon()->equals(Days::mon()) // true + Days::mon()->value === Days::tue()->value // false + Days::mon()->value === Days::mon()->value // true + ``` + +3. **Print an enum** + ``` php + echo Days::mon(); // 2 + echo Days::tue(); // 4 + echo Days::mon()->label; // Monday + ``` + As you can see enum implements the __toString method which you can override to display the label instead of the value. + This default behavior is set like this for a better behavior in laravel. + +4. **Serialise an enum** + ``` php + echo json_encode(Days::mon()); // {"label":"Monday","value":2} + ``` + Enums implement the JsonSerializable interface + +- On a Laravel project you can use enums in multiple ways + +1. **As a property** + ``` php + // Add theses to your model + use CastsEnums; + protected $enumCasts = [ + 'day' => Days::class + ]; + ``` + This will allow you model to store an enum in database using its value, and then cast the property to an enum when accessing it + +2. **As a route parameter** + + Define a route like the following + ``` php + Route::get('/days/{day}', function (Days $day) { + return response()->json([$day]); + })->middleware('bindings'); + // OR + Route::get('/days/{day}', [DayController::class, 'getDay']); + ``` + Then on your controller for the `DayController` example + ``` php + public function getDay(Request $request, Day $day) { + return response()->json([$day]); + } + ``` + +3. **As a request parameter using validation** + + Take a look at [this request example](tests/Requests/PassDayRequest.php). + + ``` php + new EnumIsValidRule(Days::class) + ``` + + It use EnumIsValidRule to validate the parameter as being a valid enum value. + + **Note that you may still have to cast your parameter to int if your enum value is an int, as enum check is strict** + +4. **As a model primary Key** + + Take a look at [unit test](tests/BaseEnumRoutableTest.php) using [the Report enum class from tests](tests/Models/Report.php) + +--- ## Change log Please see the [changelog](changelog.md) for more information on what has changed recently. +--- + ## Testing ``` bash $ composer test ``` - +--- ## Contributing Please see [contributing.md](contributing.md) for details and a todolist. +--- ## Security If you discover any security related issues, please email github@jeremydev.ovh instead of using the issue tracker. +--- ## Credits - [Jérémy Munsch][link-author]