Add Examples

Update Changelog
Update Readme

changelog.md

@@ -2,11 +2,77 @@
 
 All notable changes to `Enum` will be documented in this file.
 
-## Version 0.0.1
 
-### Initial release
+## **Version 2.1.0**
 
-## Version 0.0.2
+### Added
+
+- Full unit tests with 100% coverage
+- A laravel command to generate an Enum ``php artisan make:enum`
+- examples and a full, readme doc
+
+### Changed
+
+- Code refactoring for most of the code
+- Removed unused code parts
+- Set requirements for unit test to laravel 7
+- translations are in php files
+
+### Fixed
+
+- 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
+
+## **Version 2.0.0**
+
+### Changed
+
+- 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.
+
+## **Version 0.1.4**
+
+### Added
+
+- Validation rule EnumIsValidRule, the constructor needs a BaseEnum class
+  eg: new EnumIsValidRule(ArcadiaMailType::class)
+
+### Fixed
+
+- Unit tests with 0.1.2 changes
+
+## **Version 0.1.3**
+
+### Added
+
+- Validation rule EnumIsValidRule, the constructor needs a BaseEnum class
+  eg: new EnumIsValidRule(ArcadiaMailType::class)
+
+### 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
 
@@ -21,33 +87,6 @@ All notable changes to `Enum` will be documented in this file.
         'status' => OrderStatus::class // This is a class that extends \Kwaadpepper\Enum\BaseEnum
     ];
 
-## Version 0.1.0
+## **Version 0.0.1**
 
-### - 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.1.1
-
-### Fixed
-
-- Fixed performances issue on toValues and toLabels
-
-## Version 0.1.2
-
-### Changed
-
-- Changed toJson to output array with label and value
-
-## Version 0.1.3
-
-### Added
-
-- Validation rule EnumIsValidRule, the constructor needs a BaseEnum class
-  eg: new EnumIsValidRule(ArcadiaMailType::class)
-
-### Fixed
-
-- Unit tests with 0.1.2 changes
+### Initial release

examples/BasicEnum.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Enums;
+
+use Kwaadpepper\Enum\BaseEnumRoutable;
+
+/**
+ *
+ * @method static self child()
+ * @method static self adult()
+ * @method static self senior()
+ */
+final class BasicEnum extends BaseEnumRoutable
+{
+    //
+}

examples/Days.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace App\Enums;
+
+use Kwaadpepper\Enum\BaseEnumRoutable;
+
+/**
+ * This defines a day type with all
+ * seven days of the week, include 'none'
+ * to allow setting an 'undefined' value.
+ *
+ * @method static self none() This is used to set 'null' day
+ * @method static self mon() The first day of the week
+ * @method static self tue() The second day of the week
+ * @method static self wed() The third day of the week
+ * @method static self thu() The fourth day of the week
+ * @method static self fri() The fifth day of the week
+ * @method static self sat() The sixth day of the week
+ * @method static self sun() The last day of the week
+ */
+final class Days extends BaseEnumRoutable
+{
+    protected static function values(): array
+    {
+        return [
+            'none' => 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);
+    }
+}

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]