Custom key/context serializers

config/settings.php

@@ -112,4 +112,40 @@
     |
     */
     'team_foreign_key' => 'team_id',
+
+    /*
+    |--------------------------------------------------------------------------
+    | Context Serializer
+    |--------------------------------------------------------------------------
+    |
+    | The context serializer is responsible for converting a Context object
+    | into a string, which gets appended to a setting key in the database.
+    |
+    | Any custom serializer you use must implement the
+    | \Rawilk\Settings\Contracts\ContextSerializer interface.
+    |
+    | Supported:
+    | - \Rawilk\Settings\Support\ContextSerializers\ContextSerializer (default)
+    | - \Rawilk\Settings\Support\ContextSerializers\DotNotationContextSerializer
+    |
+    */
+    'context_serializer' => \Rawilk\Settings\Support\ContextSerializers\ContextSerializer::class,
+
+    /*
+    |--------------------------------------------------------------------------
+    | Key Generator
+    |--------------------------------------------------------------------------
+    |
+    | The key generator is responsible for generating a suitable key for a
+    | setting.
+    |
+    | Any custom key generator you use must implement the
+    | \Rawilk\Settings\Contracts\KeyGenerator interface.
+    |
+    | Supported:
+    | - \Rawilk\Settings\Support\KeyGenerators\ReadableKeyGenerator
+    | - \Rawilk\Settings\Support\KeyGenerators\Md5KeyGenerator (default)
+    |
+    */
+    'key_generator' => \Rawilk\Settings\Support\KeyGenerators\Md5KeyGenerator::class,
 ];

docs/best-practices/performance-tips.md

@@ -8,7 +8,7 @@ You are free to turn caching off, but you might notice a performance hit on larg
 on apps that are retrieving many settings on each page load.
 
 As always, if you choose to bypass the provided methods for setting and removing settings, you will need to flush the cache manually for
-each setting you manipulate manually. To determine the cache key for a setting key, you should use the `Rawilk\Settings\Support\KeyGenerator` to
+each setting you manipulate manually. To determine the cache key for a setting key, you should use the `Rawilk\Settings\Support\KeyGenerators\KeyGenerator` to
 generate the md5 version of the setting's key:
 
 ```php

src/Contracts/ContextSerializer.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rawilk\Settings\Contracts;
+
+use Rawilk\Settings\Support\Context;
+
+interface ContextSerializer
+{
+    public function serialize(Context $context = null): string;
+}

src/Contracts/KeyGenerator.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rawilk\Settings\Contracts;
+
+use Rawilk\Settings\Support\Context;
+
+interface KeyGenerator
+{
+    public function generate(string $key, Context $context = null): string;
+
+    public function setContextSerializer(ContextSerializer $serializer): self;
+}

src/Exceptions/InvalidContextValue.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rawilk\Settings\Exceptions;
+
+use Exception;
+
+final class InvalidContextValue extends Exception
+{
+    public static function forKey(string $key): self
+    {
+        return new self("An invalid context value was provided for key: {$key}. Only string, integer, and boolean values are allowed.");
+    }
+}

src/Settings.php

@@ -10,9 +10,8 @@
 use Illuminate\Support\Str;
 use Illuminate\Support\Traits\Macroable;
 use Rawilk\Settings\Contracts\Driver;
+use Rawilk\Settings\Contracts\KeyGenerator;
 use Rawilk\Settings\Support\Context;
-use Rawilk\Settings\Support\ContextSerializer;
-use Rawilk\Settings\Support\KeyGenerator;
 use Rawilk\Settings\Support\ValueSerializer;
 
 class Settings
@@ -25,8 +24,6 @@ class Settings
 
     protected ?Encrypter $encrypter = null;
 
-    protected KeyGenerator $keyGenerator;
-
     protected ValueSerializer $valueSerializer;
 
     protected bool $cacheEnabled = false;
@@ -47,9 +44,10 @@ class Settings
 
     protected string $cacheKeyPrefix = '';
 
-    public function __construct(protected Driver $driver)
-    {
-        $this->keyGenerator = new KeyGenerator(new ContextSerializer);
+    public function __construct(
+        protected Driver $driver,
+        protected KeyGenerator $keyGenerator,
+    ) {
         $this->valueSerializer = new ValueSerializer;
     }
 

src/SettingsServiceProvider.php

@@ -6,6 +6,8 @@
 
 use Rawilk\Settings\Contracts\Setting as SettingContract;
 use Rawilk\Settings\Drivers\Factory;
+use Rawilk\Settings\Support\ContextSerializers\ContextSerializer;
+use Rawilk\Settings\Support\KeyGenerators\Md5KeyGenerator;
 use Spatie\LaravelPackageTools\Package;
 use Spatie\LaravelPackageTools\PackageServiceProvider;
 
@@ -59,8 +61,14 @@ protected function registerSettings(): void
         );
 
         $this->app->singleton(Settings::class, function ($app) {
+            $keyGenerator = $this->app->make($app['config']['settings.key_generator'] ?? Md5KeyGenerator::class);
+            $keyGenerator->setContextSerializer(
+                $this->app->make($app['config']['settings.context_serializer'] ?? ContextSerializer::class)
+            );
+
             $settings = new Settings(
-                $app['SettingsFactory']->driver()
+                $app['SettingsFactory']->driver(),
+                $keyGenerator,
             );
 
             $settings->useCacheKeyPrefix($app['config']['settings.cache_key_prefix'] ?? '');

src/Support/Context.php

@@ -5,9 +5,11 @@
 namespace Rawilk\Settings\Support;
 
 use Countable;
+use Illuminate\Contracts\Support\Arrayable;
 use OutOfBoundsException;
+use Rawilk\Settings\Exceptions\InvalidContextValue;
 
-class Context implements Countable
+class Context implements Arrayable, Countable
 {
     protected array $arguments = [];
 
@@ -43,6 +45,8 @@ public function remove(string $name): self
 
     public function set(string $name, $value): self
     {
+        $this->ensureValidValue($name, $value);
+
         $this->arguments[$name] = $value;
 
         return $this;
@@ -52,4 +56,17 @@ public function count(): int
     {
         return count($this->arguments);
     }
+
+    public function toArray(): array
+    {
+        return $this->arguments;
+    }
+
+    protected function ensureValidValue(string $key, mixed $value): void
+    {
+        throw_unless(
+            is_string($value) || is_numeric($value) || is_bool($value) || is_null($value),
+            InvalidContextValue::forKey($key),
+        );
+    }
 }

src/Support/ContextSerializers/ContextSerializer.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rawilk\Settings\Support\ContextSerializers;
+
+use Rawilk\Settings\Contracts\ContextSerializer as ContextSerializerContract;
+use Rawilk\Settings\Support\Context;
+
+class ContextSerializer implements ContextSerializerContract
+{
+    public function serialize(Context $context = null): string
+    {
+        return serialize($context);
+    }
+}

src/Support/ContextSerializers/DotNotationContextSerializer.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rawilk\Settings\Support\ContextSerializers;
+
+use Rawilk\Settings\Contracts\ContextSerializer as ContextSerializerContract;
+use Rawilk\Settings\Support\Context;
+
+class DotNotationContextSerializer implements ContextSerializerContract
+{
+    public function serialize(Context $context = null): string
+    {
+        if (is_null($context)) {
+            return '';
+        }
+
+        return collect($context->toArray())
+            ->map(function ($value, string $key) {
+                // Use the model's morph class when possible.
+                $value = match ($key) {
+                    'model' => rescue(fn () => app($value)->getMorphClass(), $value),
+                    default => $value,
+                };
+
+                if ($value === false) {
+                    $value = 0;
+                }
+
+                return "{$key}:{$value}";
+            })
+            ->implode('::');
+    }
+}

src/Support/KeyGenerators/Md5KeyGenerator.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rawilk\Settings\Support\KeyGenerators;
+
+use Rawilk\Settings\Contracts\ContextSerializer;
+use Rawilk\Settings\Contracts\KeyGenerator as KeyGeneratorContract;
+use Rawilk\Settings\Support\Context;
+
+class Md5KeyGenerator implements KeyGeneratorContract
+{
+    protected ContextSerializer $serializer;
+
+    public function generate(string $key, Context $context = null): string
+    {
+        return md5($key . $this->serializer->serialize($context));
+    }
+
+    public function setContextSerializer(ContextSerializer $serializer): self
+    {
+        $this->serializer = $serializer;
+
+        return $this;
+    }
+}

src/Support/KeyGenerators/ReadableKeyGenerator.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Rawilk\Settings\Support\KeyGenerators;
+
+use Illuminate\Support\Str;
+use Rawilk\Settings\Contracts\ContextSerializer;
+use Rawilk\Settings\Contracts\KeyGenerator as KeyGeneratorContract;
+use Rawilk\Settings\Support\Context;
+
+class ReadableKeyGenerator implements KeyGeneratorContract
+{
+    protected ContextSerializer $serializer;
+
+    public function generate(string $key, Context $context = null): string
+    {
+        $key = $this->normalizeKey($key);
+
+        if ($context) {
+            $key .= ':c:::' . $this->serializer->serialize($context);
+        }
+
+        return $key;
+    }
+
+    public function setContextSerializer(ContextSerializer $serializer): KeyGeneratorContract
+    {
+        $this->serializer = $serializer;
+
+        return $this;
+    }
+
+    protected function normalizeKey(string $key): string
+    {
+        // We want to preserve period characters in the key, however everything else is fair game
+        // to convert to a slug.
+        return Str::of($key)
+            ->replace('.', '-dot-')
+            ->slug()
+            ->replace('-dot-', '.')
+            ->__toString();
+    }
+}

src/Support/ValueSerializer.php

@@ -11,8 +11,8 @@ public function serialize($value): string
         return serialize($value);
     }
 
-    public function unserialize(string $serialized)
+    public function unserialize(string $serialized): mixed
     {
-        return unserialize($serialized);
+        return unserialize($serialized, ['allowed_classes' => false]);
     }
 }