Merge branch 'release/1.1.0'

Author: Kevin Buchholz

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## NEXT RELEASE
+
+
+## 1.1.0 - 2019-04-04 - minor release
+
+### Fixed
+- the `lint:phpmd`-script no longer searches for a non existing directory
+- localization for the `EnumerationValue`-message
+
+### Changed
+- `__toString` now returns the value and not the key of the member
+
+### Added
+- `defaultMember` method to `Enumeration`
+- `HasEnums` trait for laravel models
+
+
 ## 1.0.1 - 2019-03-07 - patch release
 
 ### Fixed

README.md

@@ -27,7 +27,8 @@ Strongly typed enum implementation for Laravel. Based on [eloquent/enumeration](
 * [Methods](#methods)
 * [Validation](#validation)
 * [Localization](#localization)
-* [License information](#license-infromation)
+* [Model Trait](#model-trait)
+* [License information](#license-information)
 
 ## Requirements
 
@@ -134,6 +135,14 @@ Returns a random member from the enum. Useful for factories.
 UserType::randomMember(); // Returns Administrator(), Moderator(), Subscriber() or SuperAdministrator()
 ```
 
+### static defaultMember(): static
+
+Returns the default member for the enum. This function defaults to the first member of the enum when not overridden.
+
+``` php
+UserType::defaultMember(); // Returns Administrator()
+```
+
 ### static membersByBlacklist(?array): array
 
 Returns all members except the ones given.
@@ -142,17 +151,18 @@ Returns all members except the ones given.
 UserType::membersByBlacklist([UserType::Moderator()]); // Returns Administrator(), Subscriber() and SuperAdministrator()
 ```
 
-### static toSelectArray(): array
+### static toSelectArray(?array): array
 
-Returns the enum for use in a select as value => description.
+Returns the enum for use in a select as value => key. It is also possible to set an optional blacklist-parameter to filter the returned values.
 
 ``` php
 UserType::toSelectArray(); // Returns [0 => 'Administrator', 1 => 'Moderator', 2 => 'Subscriber', 3 => 'SuperAdministrator']
 ```
 
-### toLocalizedSelectArray(): array
+### toLocalizedSelectArray(?array): array
 
-Returns the enum for use in a select as value => description, where description is localized using `->localized()`.
+Returns the enum for use in a select as value => localizedValue, where localizedValue is localized using `->localized()`.
+Like `toSelectArray` it is possible to set an optional blacklist-parameter to filter the returned values.
 
 ``` php
 UserType::toLocalizedSelectArray(); // Returns [0 => 'Administrator', 1 => 'Moderator', 2 => 'Subscriber', 3 => 'Super Administrator']
@@ -161,7 +171,7 @@ UserType::toLocalizedSelectArray(); // Returns [0 => 'Administrator', 1 => 'Mode
 ## Validation
 
 ### Array Validation
-You may validate that an enum value passed to a controller is a valid value for a given enum by using the `EnumerationValue` rule, for easier handling there are helper methods for creating the rule: `Enumeration::makeRule()`, `Enumeration::makeRuleWithWhitelist($whitelist)` and `Enumeration::makeRuleWithBlacklist($blacklist)`.
+You may validate that a value passed to a controller is a valid value for a given enum by using the `EnumerationValue` rule, for easier handling there are helper methods for creating the rule: `Enumeration::makeRule()`, `Enumeration::makeRuleWithWhitelist($whitelist)` and `Enumeration::makeRuleWithBlacklist($blacklist)`.
 
 ``` php
 public function store(Request $request)
@@ -223,7 +233,6 @@ return [
 ```php
 // resources/lang/da/enums.php
 <?php
-
 use App\Enums\UserType;
 
 return [
@@ -235,6 +244,64 @@ 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`.
+
+To enable this functionality you will have to use the trait and set the enums property on your model.
+
+```php
+<?php
+
+namespace App\Models;
+
+use App\Enums\UserType;
+use Illuminate\Database\Eloquent\Model;
+use Sourceboat\Enumeration\Traits\HasEnums;
+
+class User extends Model
+{
+    use HasEnums;
+
+    protected $enums = [
+        'type' => 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:
+
+```php
+<?php
+
+namespace App\Models;
+
+use App\Enums\UserType;
+use Illuminate\Database\Eloquent\Model;
+use Sourceboat\Enumeration\Traits\HasEnums;
+
+class User extends Model
+{
+    use HasEnums;
+
+    protected $enums = [
+        'type' => [ 'nullable' => true, 'enum' => UserType::class ],
+    ];
+}
+```
+
+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.
+
+```php
+// For example when the value has been changed manually in the database. Let's say the type is `10`.
+$type = $user->type
+
+// Then the following will be the case:
+
+echo $type === UserType::defaultMember(); // "true"
+echo $type->value; // "0"
+```
+
 ## 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.
@@ -248,4 +315,4 @@ This package is also licensed under the MIT license.
 ## TODOs
 
 * [x]  Tests for all enumeration-functions and the rule.
-* [ ]  Model-Trait to enable casting of enumerations and "on the fly"-validation for enumeration values on models.
+* [x]  Model-Trait to enable casting of enumerations and "on the fly"-validation for enumeration values on models.

composer.json

@@ -50,11 +50,11 @@
         "test": "vendor/bin/phpunit",
         "test-coverage": "vendor/bin/phpunit --coverage-html coverage",
         "lint:phpcs": "vendor/bin/phpcs -s",
-        "lint:phpmd": "vendor/bin/phpmd config,src,tests text phpmd.xml"
+        "lint:phpmd": "vendor/bin/phpmd src,tests text phpmd.xml"
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "1.0-dev"
+            "dev-master": "1.1-dev"
         },
         "laravel": {
             "providers": [

phpcs.xml

@@ -3,7 +3,6 @@
   <description>The coding standard for this project.</description>
 
   <!-- files and folders to check -->
-  <file>resources/lang</file>
   <file>src</file>
   <file>tests</file>
 

resources/lang/en/validation.php

@@ -152,4 +152,26 @@ public static function makeRuleWithBlacklist(?array $blacklist = []): Enumeratio
     {
         return self::makeRuleWithWhitelist(self::membersByBlacklist($blacklist));
     }
+
+    /**
+     * Get the default enum member.
+     * Override for your own value / logic.
+     *
+     * @return static
+     */
+    public static function defaultMember()
+    {
+        return collect(static::members())->first();
+    }
+
+    /**
+     * Returns a string representation of this member.
+     *
+     * @return string The string representation.
+     * @phpcsSuppress SlevomatCodingStandard.TypeHints.TypeHintDeclaration.MissingReturnTypeHint
+     */
+    public function __toString()
+    {
+        return (string) $this->value();
+    }
 }

src/Enumeration.php

@@ -13,8 +13,6 @@ class EnumerationServiceProvider extends ServiceProvider
     public function boot(): void
     {
         $this->bootCommands();
-
-        $this->loadTranslationsFrom(__DIR__ . '/../lang', 'laravel_enumeration');
     }
 
     /**

src/EnumerationServiceProvider.php

@@ -4,6 +4,7 @@
 
 use Eloquent\Enumeration\Exception\UndefinedMemberExceptionInterface;
 use Illuminate\Contracts\Validation\Rule;
+use Illuminate\Support\Str;
 
 class EnumerationValue implements Rule
 {
@@ -66,7 +67,11 @@ public function passes($attribute, $value): bool
      */
     public function message(): string
     {
-        return __('laravel_enumeration::validation.enum_value');
+        $key = 'validation.enum_value';
+
+        return Str::is($key, __($key))
+            ? 'The given value is not suitable for :attribute.'
+            : __($key);
     }
 
     /**

src/Rules/EnumerationValue.php

@@ -0,0 +1,102 @@
+<?php
+
+namespace Sourceboat\Enumeration\Traits;
+
+use Eloquent\Enumeration\Exception\UndefinedMemberException;
+
+/**
+ * This trait allows for casting of model properties to enum members and
+ * setting them via enum members.
+ */
+trait HasEnums
+{
+    /**
+     * Get the attribute-enum-mapping from this model.
+     *
+     * @return array
+     */
+    public function getEnumsArray(): array
+    {
+        return $this->enums ?? [];
+    }
+
+    /**
+     * Returns whether the attribute was marked as enum.
+     *
+     * @param string $key
+     * @return bool
+     */
+    public function isEnumAttribute(string $key): bool
+    {
+        return isset($this->getEnumsArray()[$key]);
+    }
+
+    /**
+     * Get an attribute from the model.
+     *
+     * @param string $key
+     * @return mixed
+     * @phpcsSuppress SlevomatCodingStandard.TypeHints.TypeHintDeclaration.MissingParameterTypeHint
+     */
+    public function getAttribute($key)
+    {
+        if ($this->isEnumAttribute($key)) {
+            $class = $this->getEnumsArray()[$key];
+            $nullable = false;
+
+            if (is_array($class)) {
+                $nullable = $class['nullable'];
+                $class = $class['enum'];
+            }
+
+            try {
+                return $class::memberByValue($this->getAttributeFromArray($key));
+            } catch (UndefinedMemberException $e) {
+                if ($nullable && is_null($this->getAttributeFromArray($key))) {
+                    return null;
+                }
+
+                return $class::defaultMember();
+            }
+        }
+
+        return parent::getAttribute($key);
+    }
+
+    /**
+     * Set a given attribute on the model.
+     *
+     * @param string $key
+     * @param mixed $value
+     * @return $this
+     * @phpcsSuppress SlevomatCodingStandard.TypeHints.TypeHintDeclaration.MissingParameterTypeHint
+     */
+    public function setAttribute($key, $value)
+    {
+        if ($this->isEnumAttribute($key)) {
+            $class = $this->getEnumsArray()[$key];
+            $nullable = false;
+
+            if (is_array($class)) {
+                $nullable = $class['nullable'];
+                $class = $class['enum'];
+            }
+
+            if ($nullable && is_null($value)) {
+                $this->attributes[$key] = $value;
+
+                return $this;
+            }
+
+            if (! $value instanceof $class) {
+                $value = $class::memberByValue($value);
+            }
+
+            $this->attributes[$key] = $value->value();
+
+            return $this;
+        }
+
+        parent::setAttribute($key, $value);
+    }
+}

src/Traits/HasEnums.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Sourceboat\Enumeration\Tests;
+
+use Sourceboat\Enumeration\Enumeration;
+
+/**
+ * @method static \Sourceboat\Enumeration\Tests\FruitType BERRY()
+ * @method static \Sourceboat\Enumeration\Tests\FruitType NUT()
+ * @method static \Sourceboat\Enumeration\Tests\FruitType ACCESSORY_FRUIT()
+ * @method static \Sourceboat\Enumeration\Tests\FruitType LEGUME()
+ */
+class FruitType extends Enumeration
+{
+    protected static $localizationPath = 'test';
+
+    public const BERRY = 'berry';
+    public const NUT = 'nut';
+    public const ACCESSORY_FRUIT = 'accessory_fruit';
+    public const LEGUME = 'legume';
+}