feat:

api improvements:
- to dto transformation for the api
- allow all datatypes(except object) to be passed via api
2 new Rules

fix:
 - inconsistent ValueCaster behaviour
 - InstanceOfRule did not consider the class itself, only its parents

Author: matteoc99

README.md

@@ -48,9 +48,15 @@ This Laravel package aims to store and manage user settings/preferences in a sim
 ### Roadmap
 
 - Additional inbuilt Custom Rules -> v2.x
-- Policies: ~2.0.0-beta.5
+- Api Enum support -> v2.2
 - Suggestions are welcome
 
+### Known Issues
+`Cast::Object`: internally, laravel tries the toArray() 
+if the object implements Arrayable, resulting in an array rather than an object as required by the validation   
+
+Consider sticking to Enums or Primitive casts for now
+
 ## Installation
 
 You can install the package via composer:
@@ -416,6 +422,9 @@ implement `PreferencePolicy` and the 4 methods defined by the contract
 
 off by default, enable it in the config
 
+> Current limitation: it's not possible to set enums/object casts via API  
+> Enum support planned for v2.2
+
 ### Anantomy:
 
 'Scope': the `PreferenceableModel` Model  

config/user_preference.php

@@ -4,12 +4,13 @@
     'db'           => [
         'connection'                  => null,
         'preferences_table_name'      => 'preferences',
-        'user_preferences_table_name' => 'user_preferences',
+        'user_preferences_table_name' => 'users_preferences',
     ],
     'xss_cleaning' => true,
     'routes'       => [
         'enabled'     => false,
         'middlewares' => [
+            'web', // required for Auth::user() and policies
             'auth', // general middleware
             'user'         => 'verified', // optional, scoped middleware
             'user.general' => 'verified' // optional, scoped & grouped middleware

database/migrations/2024_04_21_10000_add_allowed_values.php

@@ -0,0 +1,27 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+use Matteoc99\LaravelPreference\Models\Preference;
+
+return new class extends Migration {
+
+    public function up()
+    {
+        $preferenceTable = (new Preference())->getTable();
+
+        Schema::table($preferenceTable, function (Blueprint $table) {
+            $table->json('allowed_values')->nullable();
+        });
+    }
+
+    public function down()
+    {
+        $preferenceTable = (new Preference())->getTable();
+
+        Schema::table($preferenceTable, function (Blueprint $table) {
+            $table->dropColumn('allowed_values');
+        });
+    }
+};

src/Casts/ValueCaster.php

@@ -15,7 +15,7 @@ public function get(?Model $model, string $key, mixed $value, array $attributes)
     {
         if (is_null($value)) return null;
 
-        $caster = $this->getCaster($model);
+        $caster = $this->getCaster($model, $attributes);
 
         if ($caster) {
             return $caster->castFromString($value);
@@ -29,19 +29,30 @@ public function set(?Model $model, string $key, mixed $value, array $attributes)
     {
         if (is_null($value)) return null;
 
-        $caster = $this->getCaster($model);
+        $caster = $this->getCaster($model, $attributes);
 
         if ($caster) {
             return $caster->castToString($value);
         }
 
-        //default do nothing
         return $value;
     }
 
-    private function getCaster(?Model $model): CastableEnum|null
+    private function getCaster(?Model $model, array $attributes): CastableEnum|null
     {
-        $caster = $this->caster ?? $model?->cast ?? $model?->preference?->cast ?? null;
+        if (array_key_exists('cast', $attributes)) {
+            $caster = unserialize($attributes['cast']);
+        } else if (is_null($model)) {
+            $caster = $this->caster;
+        } else {
+            $caster = $model->cast ?? null;
+            if (is_null($caster) && $model->isRelation('preference')) {
+                if (!$model->relationLoaded('preference')) {
+                    $model->load('preference');
+                }
+                $caster = $model->preference->cast ?? null;
+            }
+        }
 
         return $caster instanceof CastableEnum ? $caster : null;
     }

src/Contracts/CastableEnum.php

@@ -14,4 +14,13 @@ public function validation(): ValidationRule|array|string|null;
     public function castToString(mixed $value): string;
 
     public function castFromString(string $value): mixed;
+
+
+    /**
+     * used by the Controller to cast to json
+     * @param mixed $value
+     *
+     * @return array
+     */
+    public function castToDto(mixed $value): array;
 }

src/Contracts/PreferenceableModel.php

@@ -2,11 +2,13 @@
 
 namespace Matteoc99\LaravelPreference\Contracts;
 
+use Illuminate\Auth\Access\AuthorizationException;
 use Illuminate\Contracts\Auth\Authenticatable;
 use Illuminate\Support\Collection;
 use Illuminate\Validation\ValidationException;
 use Matteoc99\LaravelPreference\Enums\PolicyAction;
 use Matteoc99\LaravelPreference\Exceptions\PreferenceNotFoundException;
+use Matteoc99\LaravelPreference\Models\Preference;
 
 interface PreferenceableModel
 {
@@ -51,6 +53,17 @@ public function setPreference(PreferenceGroup $name, mixed $value): void;
      */
     public function getPreference(PreferenceGroup $name, mixed $default = null): mixed;
 
+    /**
+     * Get a user's preference value or default if not set with no casting
+     *
+     * @param PreferenceGroup|Preference $preference
+     * @param string|null                $default Default value if preference not set.
+     *
+     * @return array
+     * @throws AuthorizationException
+     * @throws PreferenceNotFoundException
+     */
+    public function getPreferenceDto(PreferenceGroup|Preference $preference, mixed $default = null): array;
 
     /**
      * check if the user is authorized

src/Enums/Cast.php

@@ -10,6 +10,7 @@
 use Matteoc99\LaravelPreference\Contracts\CastableEnum;
 use Matteoc99\LaravelPreference\Rules\InstanceOfRule;
 use Matteoc99\LaravelPreference\Rules\IsRule;
+use Matteoc99\LaravelPreference\Rules\OrRule;
 use UnitEnum;
 
 
@@ -39,15 +40,39 @@ public function validation(): ValidationRule|array|string|null
             self::STRING => 'string',
             self::BOOL => 'boolean',
             self::ARRAY => 'array',
-            self::DATE, self::DATETIME => 'date',
-            self::TIME => 'date_format:H:i',
-            self::TIMESTAMP => 'date_format:U',
+            self::DATE => new OrRule('date','date_format:Y-m-d', new InstanceOfRule(Carbon::class)),
+            self::DATETIME => new OrRule('date', new InstanceOfRule(Carbon::class)),
+            self::TIME => new OrRule('date_format:H:i', 'date_format:H:i:s', new InstanceOfRule(Carbon::class)),
+            self::TIMESTAMP => new OrRule('date_format:U', new InstanceOfRule(Carbon::class)),
             self::BACKED_ENUM => new InstanceOfRule(BackedEnum::class),
             self::ENUM => new InstanceOfRule(UnitEnum::class),
             self::OBJECT => new IsRule(Type::OBJECT),
         };
     }
 
+    /**
+     * @throws ValidationException
+     */
+    public function castToDto(mixed $value): array
+    {
+        return match ($this) {
+            self::NONE,
+            self::BACKED_ENUM,
+            self::ARRAY,
+            self::ENUM,
+            self::OBJECT => $this->valueToArray($value),
+            self::INT,
+            self::FLOAT,
+            self::STRING,
+            self::BOOL,
+            self::TIMESTAMP,
+            self::TIME,
+            self::DATE,
+            self::DATETIME => $this->valueToArray($this->castToString($value)),
+        };
+    }
+
+
     public function castFromString(string $value): mixed
     {
         return match ($this) {
@@ -154,4 +179,22 @@ private function ensureObject(mixed $value)
         }
         return $value;
     }
+
+    private function valueToArray(mixed $value): array
+    {
+        if (is_object($value) && method_exists($value, 'toArray')) {
+            return [
+                'value' => $value->toArray()
+            ];
+        }
+
+        if (!is_array($value)) {
+            return ['value' => is_string($value) ? $value : $this->castToString($value)];
+        }
+
+        return [
+            'value' => $value
+        ];
+    }
+
 }

src/Factory/PreferenceBuilder.php

@@ -82,6 +82,21 @@ public function withRule(ValidationRule $rule): static
         return $this;
     }
 
+    public function setAllowedClasses(...$classes): static
+    {
+        if( in_array($this->preference->cast,[Cast::OBJECT,Cast::ENUM,Cast::BACKED_ENUM])){
+            throw new InvalidArgumentException("Allowed classes are not supported for primitive casts");
+        }
+        foreach ($classes as $class) {
+            if (!is_string($class)) {
+                throw new InvalidArgumentException("All allowed classes must be strings.");
+            }
+        }
+
+        $this->preference->allowed_values = $classes;
+        return $this;
+    }
+
     public function nullable(bool $nullable = true)
     {
         $this->preference->nullable = $nullable;

src/Http/Controllers/PreferenceController.php

@@ -39,9 +39,7 @@ public function __construct(Request $request)
     public function index(Request $request): JsonResponse
     {
         try {
-            return $this->prepareResponse(
-                $this->scope->getPreferences($this->group)
-            );
+            return response()->json($this->scope->getPreferences($this->group));
         } catch (Throwable $exception) {
             $this->handleException($exception);
         }
@@ -50,9 +48,7 @@ public function index(Request $request): JsonResponse
     public function get(Request $request): JsonResponse
     {
         try {
-            return $this->prepareResponse(
-                $this->scope->getPreference($this->group)
-            );
+            return $this->prepareResponse();
         } catch (Throwable $exception) {
             $this->handleException($exception);
         }
@@ -67,9 +63,7 @@ public function update(PreferenceUpdateRequest $request): JsonResponse
 
             $this->scope->setPreference($this->group, $value);
 
-            return $this->prepareResponse(
-                $this->scope->getPreference($this->group)
-            );
+            return $this->prepareResponse();
         } catch (Throwable $exception) {
             return $this->handleException($exception);
         }
@@ -80,9 +74,7 @@ public function delete(Request $request): JsonResponse
         try {
             $this->scope->removePreference($this->group);
 
-            return $this->prepareResponse(
-                $this->scope->getPreference($this->group)
-            );
+            return $this->prepareResponse();
         } catch (Throwable $exception) {
             $this->handleException($exception);
         }
@@ -149,18 +141,13 @@ private function extractScopeAndGroup($routeName): array
         ];
     }
 
-    private function prepareResponse(mixed $pref): JsonResponse
+    /**
+     * @throws AuthorizationException
+     * @throws PreferenceNotFoundException
+     */
+    private function prepareResponse(): JsonResponse
     {
-        if (!empty($pref) && is_object($pref) && method_exists($pref, 'toArray')) {
-            $pref = $pref->toArray();
-        }
-
-        if (!is_array($pref)) {
-            $pref = [
-                'value' => $pref,
-            ];
-        }
-        return response()->json($pref);
+        return response()->json($this->scope->getPreferenceDto($this->group));
     }
 
     /**
@@ -176,7 +163,7 @@ private function handleException(Throwable|\Exception $exception)
         };
     }
 
-    private function clean(mixed &$value)
+    private function clean(mixed &$value): void
     {
         if (ConfigHelper::isXssCleanEnabled()) {
             if (is_string($value)) {

src/Models/Preference.php

@@ -22,6 +22,7 @@
  * @property ValidationRule|null   $rule
  * @property PreferencePolicy|null $policy
  * @property mixed                 $default_value
+ * @property string[]              $allowed_values
  * @property boolean               $nullable
  * @property Carbon                $created_at
  * @property Carbon                $updated_at
@@ -40,16 +41,18 @@ class Preference extends BaseModel
         'nullable',
         'rule',
         'default_value',
+        'allowed_values',
     ];
 
     protected $casts = [
-        'created_at'    => 'datetime',
-        'updated_at'    => 'datetime',
-        'cast'          => SerializingCaster::class,
-        'rule'          => SerializingCaster::class,
-        'policy'        => SerializingCaster::class,
-        'default_value' => ValueCaster::class,
-        'nullable'      => 'boolean',
+        'created_at'     => 'datetime',
+        'updated_at'     => 'datetime',
+        'cast'           => SerializingCaster::class,
+        'rule'           => SerializingCaster::class,
+        'policy'         => SerializingCaster::class,
+        'default_value'  => ValueCaster::class,
+        'allowed_values' => 'array',
+        'nullable'       => 'boolean',
     ];
 
 }

src/Rules/BetweenRule.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Matteoc99\LaravelPreference\Rules;
+
+
+use Closure;
+use Illuminate\Contracts\Validation\ValidationRule;
+
+class BetweenRule implements ValidationRule
+{
+
+    public function __construct(protected float $min, protected float $max)
+    {
+    }
+
+    public function validate(string $attribute, mixed $value, Closure $fail): void
+    {
+        if (!is_numeric($value)) {
+            $fail("A number is expected");
+        }
+        if ($value < $this->min || $value > $this->max) {
+            $fail("The number is expected to be between $this->min and $this->max");
+        }
+    }
+}