Merge branch 'release/2.0.0'

Author: Kevin Buchholz

.travis.yml

@@ -1,20 +1,18 @@
 language: php
 
 php:
-  - 7.1
-  - 7.2
   - 7.3
-  - 7.4snapshot
+  - 7.4
   - nightly
 
 matrix:
   include:
-  - php: 7.1
+  - php: 7.3
     env: COMPOSER_FLAGS="--prefer-lowest"
-  - php: 7.2
+  - php: 7.4
     env: COMPOSER_FLAGS="--prefer-lowest"
+  - php: 7.4
   allow_failures:
-  - php: 7.4snapshot
   - php: nightly
 
 before_script:

CHANGELOG.md

@@ -3,6 +3,20 @@
 ## Next release
 
 
+## 2.0.0 - 2020-03-29 - major release
+
+### Added
+- Laravel 7.x support
+- Laravel 7 custom casts
+- `Configurable`-trait for enums
+
+### Changed
+- Dropped Support for version of Laravel lower than 7.0
+- Dropped Support for versions of PHP lower than 7.3
+- Removed `HasEnums`-trait in favor of custom casts
+- Removed possibility to set weight path by static property to prevent notices when accessing undefined properties
+
+
 ## 1.3.0 - 2019-08-31 - minor release
 
 ### Added

README.md

@@ -27,29 +27,22 @@ Enum implementation for Laravel. Based on [eloquent/enumeration](https://github.
 * [Methods](#methods)
 * [Validation](#validation)
 * [Localization](#localization)
-* [Model Trait](#model-trait)
+* [Custom cast](#custom-cast)
 * [Weighted Enums](#weighted-enums)
 * [License information](#license-information)
 
 ## Requirements
 
 * eloquent/enumeration 6.0 or newer
-* Laravel 5.7 or newer;
-* PHP 7.1 or newer
+* Laravel 7 or newer;
+* PHP 7.3 or newer
 
 ## Install
 
 Via Composer
 
 ``` bash
-
-$ composer require sourceboat/laravel-enumeration
-```
-
-If you're using Laravel < 5.5 you'll need to add the service provider to `config/app.php`
-
-``` php
-'Sourceboat\Enumeration\EnumerationServiceProvider'
+composer require sourceboat/laravel-enumeration
 ```
 
 ## Generating enums
@@ -269,11 +262,9 @@ return [
 ];
 ```
 
-## Model Trait
-
-You can use the `HasEnums` trait to enable automatic casting of properties to enums. When used, it also automatically checks if a value set to an enum property is valid, if not it throws an `UndefinedMemberException`.
+## Custom Cast
 
-To enable this functionality you will have to use the trait and set the enums property on your model.
+You can use the `Enum` custom cast to enable automatic casting of properties to enums. When used, it will set the property to the default members value when set to an invalid value, same goes when the initial value is invalid when getting it, it will return the default member.
 
 ```php
 <?php
@@ -282,19 +273,17 @@ namespace App\Models;
 
 use App\Enums\UserType;
 use Illuminate\Database\Eloquent\Model;
-use Sourceboat\Enumeration\Traits\HasEnums;
+use Sourceboat\Enumeration\Casts\Enum;
 
 class User extends Model
 {
-    use HasEnums;
-
-    protected $enums = [
-        'type' => UserType::class,
+    protected $casts = [
+        'type' => Enums::class . ':' . UserType::class,
     ];
 }
 ```
 
-The enums property is a simple mapping of model attributes to enum classes. For cases where you want an attribute to be nullable, but don't want to have a `null`-value member in your enum, you can specify this explicitly:
+By default the custom cast treats the property as nullable, meaning that the property can be set to null and also return it, instead of an enum member, this can the disabled on an per property basis:
 
 ```php
 <?php
@@ -303,16 +292,14 @@ namespace App\Models;
 
 use App\Enums\UserType;
 use Illuminate\Database\Eloquent\Model;
-use Sourceboat\Enumeration\Traits\HasEnums;
+use Sourceboat\Enumeration\Casts\Enum;
 
 class User extends Model
 {
-    use HasEnums;
-
-    protected $enums = [
-        'type' => [ 'nullable' => true, 'enum' => UserType::class ],
-    ];
-}
+    protected $casts = [
+        'type' => Enums::class . ':' . UserType::class . ',0', // appending the 0 means it is not nullable,
+    ];                                                         // this seems counter intuitive, but thats the way it is recognized as `false`,
+}                                                              // as `false` is somehow evaluated as `true`.
 ```
 
 If the casted attribute is not set to be nullable and/or has a value not represented by the enum, you will get the default member of the enum when accessing the attribute.
@@ -329,7 +316,7 @@ echo $type->value; // "0"
 
 ## Weighted Enums
 
-It is Possible to define weights for enum members. the standard way is to define the weights a config file and them implement the `Weighted`-interface with the `IsWeighted`-trait and define the path to your config. The weigths can be defined as integer or float values.
+It is Possible to define weights for enum members. the standard way is to define the weights a config file and them implement the `Weighted`-interface with the `IsWeighted`-trait and define the path to your config. The weights can be defined as integer or float values.
 
 ``` php
 // The Enum
@@ -355,8 +342,6 @@ final class UserType extends Enumeration implements Weighted
     const Moderator = 1;
     const Subscriber = 2;
     const SuperAdministrator = 3;
-
-    protected static $weightOptionsKey = 'test'; // optional, by standard its `sprintf('enums.%s.weights', static::class)`
 }
 ```
 
@@ -399,6 +384,70 @@ Available scopes:
 * `whereBetweenEnum(string $attribute, Weighted $lowerMember, Weighted $higherMember)`
 * `whereBetweenOrEqualEnum(string $attribute, Weighted $lowerMember, Weighted $higherMember)`
 
+
+## Configurable Enums
+
+It is possible to define config values for enums and access them without defining the whole path, but a logical part of it.
+The default path for the configuration is: `enums.<enum class>.<given key>.<enum value>`
+
+For example:
+
+``` php
+// The Enum
+<?php
+
+namespace App\Enums;
+
+use Sourceboat\Enumeration\Enumeration;
+use Sourceboat\Enumeration\Enums\Interfaces\Configurable;
+use Sourceboat\Enumeration\Enums\Traits\IsConfigurable;
+
+/**
+ * @method static \App\Enums\UserType Administrator()
+ * @method static \App\Enums\UserType Moderator()
+ * @method static \App\Enums\UserType Subscriber()
+ * @method static \App\Enums\UserType SuperAdministrator()
+ */
+final class UserType extends Enumeration implements Configurable
+{
+    use IsConfigurable;
+
+    const Administrator = 0;
+    const Moderator = 1;
+    const Subscriber = 2;
+    const SuperAdministrator = 3;
+}
+```
+
+``` php
+// enums.php
+<?php
+use App\Enums\UserType;
+
+return [
+    UserType::class => [
+        'permissions' => [
+            UserType::Administrator => [
+                'user.foreign.edit',
+                'user.foreign.delete',
+            ],
+            UserType::Subscriber => [
+                'user.self.edit',
+                'user.self.delete',
+            ],
+        ]
+    ]
+]
+```
+
+then you can access these values by:
+
+``` php 
+UserType::Subscriber()->config('permissions'); // which return the given array.
+UserType::Moderator()->config('permissions', ['thread.foreign.archive']); // you can also define a default value.
+```
+
+
 ## License information
 
 Much of the functionality in this Package is inspired by [bensampo/laravel-enum](https://github.com/bensampo/laravel-enum) and some code has been taken from it and modified, for example the `MakeEnumCommand.php`, the `EnumServiceProvider.php` and this readme.

composer.json

@@ -24,17 +24,19 @@
         }
     ],
     "require": {
-        "php": ">=7.1",
+        "php": ">=7.3",
         "eloquent/enumeration": "^6.0",
-        "laravel/framework": "5.7.* || 5.8.* || ^6.0"
+        "illuminate/console": ">=7.0",
+        "illuminate/contracts": ">=7.0",
+        "illuminate/support": ">=7.0"
     },
     "require-dev": {
-        "consistence/coding-standard": "3.7",
-        "orchestra/testbench": "~3.0 || 4.*",
+        "consistence/coding-standard": "3.10",
+        "orchestra/testbench": "^5.0",
         "phpmd/phpmd": "^2.6",
-        "phpunit/phpunit": "7.4.* || 8.3.* || 8.4.* || 8.5.*",
-        "slevomat/coding-standard": "4.8.7",
-        "squizlabs/php_codesniffer": "^3.4"
+        "phpunit/phpunit": "8.3.* || 8.4.* || 8.5.* || 9.0.*",
+        "slevomat/coding-standard": "6.0.8",
+        "squizlabs/php_codesniffer": "^3.5"
     },
     "autoload": {
         "psr-4": {

phpcs.xml

@@ -34,7 +34,6 @@
     <exclude name="SlevomatCodingStandard.Namespaces.FullyQualifiedClassNameAfterKeyword.NonFullyQualifiedExtends"/>
     <exclude name="SlevomatCodingStandard.Namespaces.FullyQualifiedClassNameAfterKeyword.NonFullyQualifiedUse"/>
     <exclude name="SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly.PartialUse"/>
-    <exclude name="SlevomatCodingStandard.Types.EmptyLinesAroundTypeBraces"/>
     <exclude name="SlevomatCodingStandard.TypeHints.DeclareStrictTypes.DeclareStrictTypesMissing" />
     <exclude name="SlevomatCodingStandard.TypeHints.TypeHintDeclaration.MissingTraversablePropertyTypeHintSpecification"/>
     <exclude name="SlevomatCodingStandard.TypeHints.TypeHintDeclaration.MissingTraversableParameterTypeHintSpecification"/>
@@ -47,6 +46,9 @@
     <exclude name="SlevomatCodingStandard.ControlStructures.ControlStructureSpacing.IncorrectLinesCountAfterControlStructure"/>
     <exclude name="SlevomatCodingStandard.ControlStructures.DisallowShortTernaryOperator.DisallowedShortTernaryOperator"/>
     <exclude name="SlevomatCodingStandard.Operators.DisallowIncrementAndDecrementOperators.DisallowedPostIncrementOperator"/>
+    <exclude name="SlevomatCodingStandard.TypeHints.PropertyTypeHint"/>
+    <exclude name="SlevomatCodingStandard.TypeHints.DisallowMixedTypeHint"/>
+    <exclude name="SlevomatCodingStandard.Functions.RequireArrowFunction"/>
 	</rule>
 
   <!-- exclude directories from certain rules -->
@@ -57,7 +59,11 @@
   <rule ref="PSR1.Classes.ClassDeclaration.MissingNamespace">
     <exclude-pattern>*/database/*</exclude-pattern>
   </rule>
-  <rule ref="SlevomatCodingStandard.TypeHints.TypeHintDeclaration.MissingPropertyTypeHint">
-    <exclude-pattern>*/tests/*</exclude-pattern>
+
+  <rule ref="SlevomatCodingStandard.Classes.EmptyLinesAroundClassBraces">
+    <properties>
+        <property name="linesCountAfterOpeningBrace" value="0" />
+        <property name="linesCountBeforeClosingBrace" value="0" />
+    </properties>
   </rule>
 </ruleset>

phpmd.xml

@@ -3,6 +3,7 @@
     <description>The coding standard for this project.</description>
     <rule ref="rulesets/cleancode.xml">
       <exclude name="StaticAccess" />
+      <exclude name="BooleanArgumentFlag" />
     </rule>
     <rule ref="rulesets/codesize.xml" />
     <rule ref="rulesets/controversial.xml" />

src/Casts/Enum.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Sourceboat\Enumeration\Casts;
+
+use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
+
+class Enum implements CastsAttributes
+{
+    private $enumClass;
+
+    private $nullable;
+
+    public function __construct(string $enumClass, bool $nullable = true)
+    {
+        $this->enumClass = $enumClass;
+        $this->nullable = $nullable;
+    }
+
+    /**
+     * Transform the attribute from the underlying model values.
+     *
+     * @param  \Illuminate\Database\Eloquent\Model  $model
+     * @param  string  $key
+     * @param  mixed  $value
+     * @param  array<mixed>  $attributes
+     * @return self|null
+     * @phpcsSuppress SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
+     * @phpcsSuppress SlevomatCodingStandard.TypeHints.ReturnTypeHint.MissingNativeTypeHint
+     * @SuppressWarnings(PHPMD.UnusedFormalParameter)
+     */
+    public function get($model, string $key, $value, array $attributes)
+    {
+        if ($this->enumClass::hasValue($value)) {
+            return $this->enumClass::memberByValue($value);
+        }
+
+        if ($this->nullable && is_null($value)) {
+            return $value;
+        }
+
+        return $this->enumClass::defaultMember();
+    }
+
+    /**
+     * Transform the attribute to its underlying model values.
+     *
+     * @param  \Illuminate\Database\Eloquent\Model  $model
+     * @param  string  $key
+     * @param  mixed  $value
+     * @param  array<mixed>  $attributes
+     * @return array<mixed>
+     * @phpcsSuppress SlevomatCodingStandard.TypeHints.ParameterTypeHint.MissingNativeTypeHint
+     * @SuppressWarnings(PHPMD.UnusedFormalParameter)
+     */
+    public function set($model, string $key, $value, array $attributes): array
+    {
+        if ($this->enumClass::hasValue($value)
+            || ($this->nullable && is_null($value))) {
+            return [
+                $key => $value,
+            ];
+        }
+
+        if ($value instanceof $this->enumClass) {
+            return [
+                $key => $value->value(),
+            ];
+        }
+
+        return [
+            $key => $this->enumClass::defaultMember()->value(),
+        ];
+    }
+}