Merge pull request #36 from spatie/v2

V2

Author: rubenvanassche

CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `laravel-settings` will be documented in this file
 
+## 2.0.0 - 2020-03-03
+
+- settings classes:
+    - properties won't be loaded when constructed but when requested
+    - receive a `SettingsMapper` when constructed
+    - faking settings will now only request non-given properties from the repository
+- rewritten `SettingsMapper` from scratch
+- removed `SettingsPropertyData` and `ettingsPropertyDataCollection`
+- changed signatures of `SavingSettings` and `LoadingSettings` events
+- added support for caching settings
+- renamed `cache_path` in settings.php to `discovered_settings_cache_path`
+
 ## 1.0.8 - 2020-03-03
 
 - fix for properties without defined type
@@ -12,19 +24,19 @@ All notable changes to `laravel-settings` will be documented in this file
 
 ## 1.0.6 - 2020-02-05
 
--  add support for restoring settings after a Laravel schema:dump
+- add support for restoring settings after a Laravel schema:dump
 
 ## 1.0.5 - 2020-01-29
 
--  bump the `doctrine/dbal` dependency
+- bump the `doctrine/dbal` dependency
 
 ## 1.0.4 - 2020-01-08
 
--  add support for getting the locked settings
+- add support for getting the locked settings
 
 ## 1.0.3 - 2020-11-26
 
--  add PHP 8 support
+- add PHP 8 support
 
 ## 1.0.2 - 2020-11-26
 

README.md

@@ -89,10 +89,12 @@ php artisan vendor:publish --provider="Spatie\LaravelSettings\LaravelSettingsSer
 This is the contents of the published config file:
 
 ```php
+
 return [
 
     /*
-     * You can register all the settings classes here.
+     * Each settings class used in your application must be registered, you can
+     * put them (manually) here.
      */
     'settings' => [
 
@@ -102,22 +104,17 @@ return [
      * When you create a new settings migration via the `make:settings-migration`
      * command the package will store these migrations in this directory.
      */
-
     'migrations_path' => database_path('settings'),
 
     /*
-     * When no repository was set for a settings class this repository will be
-     * used for loading and saving settings.
+     * When no repository was set for a settings class the following repository
+     * will be used for loading and saving settings.
      */
-
     'default_repository' => 'database',
 
     /*
-     * Settings will be stored and loaded from these repositories. There are
-     * Two types of repositories: database and Redis. But its always
-     * possible to create your specific types of repositories.
+     * Settings will be stored and loaded from these repositories.
      */
-
     'repositories' => [
         'database' => [
             'type' => Spatie\LaravelSettings\SettingsRepositories\DatabaseSettingsRepository::class,
@@ -132,11 +129,20 @@ return [
     ],
 
     /*
-     * When the package discovers a setting with a type other than the PHP built
-     * in types, it should be cast. These casts will automatically cast types
-     * when they occur in a settings class.
+     * The contents of settings classes can be cached through your application,
+     * settings will be stored within a provided Laravel store and can have an
+     * additional prefix.
      */
+    'cache' => [
+        'enabled' => env('SETTINGS_CACHE_ENABLED', false),
+        'store' => null,
+        'prefix' => null,
+    ],
 
+    /*
+     * These global casts will be automatically used whenever a property within
+     * your settings class isn't a default PHP type.
+     */
     'global_casts' => [
         DateTimeInterface::class => Spatie\LaravelSettings\SettingsCasts\DateTimeInterfaceCast::class,
         DateTimeZone::class => Spatie\LaravelSettings\SettingsCasts\DateTimeZoneCast::class,
@@ -147,20 +153,16 @@ return [
      * The package will look for settings in these paths and automatically
      * register them.
      */
-
     'auto_discover_settings' => [
         app()->path(),
     ],
 
     /*
-     * When in production, it is advised to cache the automatically discovered
-     * and registered setting classes will be cached in this path.
+     * Automatically discovered settings classes can be cached so they don't
+     * need to be searched each time the application boors up.
      */
-
-    'cache_path' => storage_path('app/laravel-settings'),
+    'discovered_settings_cache_path' => storage_path('app/laravel-settings'),
 ];
-
-
 ```
 
 ## Usage
@@ -190,7 +192,8 @@ Now, you will have to add this settings class to the `settings.php` config file
 
 ```php
     /*
-     * You can register all the settings classes here.
+     * Each settings class used in your application must be registered, you can
+     * put them (manually) here.
      */
     'settings' => [
         GeneralSettings::class
@@ -316,7 +319,7 @@ class CreateGeneralSettings extends SettingsMigration
 }
 ```
 
-We haven't added a `down` method, but this can be added if required. In the `up` method, you can change the settings data in a repository when migrating. There are a few default operations supported:
+We haven't added a `down` method, but this can be added if disered. In the `up` method, you can change the settings data in a repository when migrating. There are a few default operations supported:
 
 #### Adding a property
 
@@ -703,6 +706,30 @@ DateSettings::fake([
 
 Now, when the `DateSettings` settings class is injected somewhere in your application, the `birth_date` property will be `DateTime('16-05-1994')`.
 
+### Caching settings
+
+It takes a small amount of time to load a settings class from a repository. When you've got many settings classes, these added small amounts of time can grow quickly out of hand. The package has built-in support for caching stored settings using the Laravel cache.
+
+You should first enable the cache within the `settings.php` config file:
+
+```php
+'cache' => [
+    'enabled' => env('SETTINGS_CACHE_ENABLED', false),
+    'store' => null,
+    'prefix' => null,
+],
+```
+
+We suggest you enable caching in production by adding `SETTINGS_CACHE_ENABLED=true` to your `.env` file. It is also possible to define a store for the cache, which should be one of the stores you defined in the `cache.php` config file. If no store were defined, the default cache store would be taken. To avoid conflicts within the cache, you can also define a prefix that will be added to each cache entry.
+
+That's it. The package is now smart enough to cache the settings the first time they're loaded. Whenever the settings are edited, the package will refresh the settings.
+
+You can always clear the cached settings with the following command:
+
+```bash
+php artisan settings:clear-cache
+```
+
 ### Auto discovering settings classes
 
 Each settings class you create should be added to the `settings` array within the `settings.php` config file. When you've got a lot of settings, this can be quickly forgotten.
@@ -967,6 +994,15 @@ It is required to return raw values again in the `getPropertiesInGroup` and `get
 
 Each repository's constructor will receive a `$config` array that the user-defined for the repository within the application `settings.php` config file. It is possible to add other dependencies to the constructor. They will be injected when the repository is created.
 
+### Events
+
+The package will emit a series of events when loading/saving settings classes:
+
+- `LoadingSettings` whenever settings are loaded from the repository but not yet inserted in the settings class
+- `LoadedSettings` after settings are loaded into the settings class
+- `SavingSettings` whenever settings are saved to the repository but are not yet cast or encrypted
+- `SavedSettings` after settings are stored within the repository
+
 ## Testing
 
 ``` bash

composer.json

@@ -18,20 +18,20 @@
     "require": {
         "php": "^7.4|^8.0",
         "ext-json": "*",
-        "illuminate/database": "^7.0|^8.0",
+        "illuminate/database": "^7.0|^8.24.0",
         "doctrine/dbal" : "^2.6|^3",
         "phpdocumentor/type-resolver": "^1.4",
         "spatie/data-transfer-object": "^2.0",
         "spatie/temporary-directory": "^1.2"
     },
     "require-dev": {
+        "ext-redis": "*",
+        "mockery/mockery": "^1.4",
         "orchestra/testbench": "^5.0|^6.0",
-        "mockery/mockery" : "^1.4",
         "phpunit/phpunit": "^9.1",
         "psalm/plugin-laravel": "^1.4",
         "spatie/phpunit-snapshot-assertions": "^4.2",
-        "vimeo/psalm": "^4.2",
-        "ext-redis" : "*"
+        "vimeo/psalm": "^4.2"
     },
     "autoload": {
         "psr-4": {
@@ -44,7 +44,7 @@
         }
     },
     "scripts": {
-        "psalm": "vendor/bin/psalm",
+        "psalm": "vendor/bin/psalm --no-diff",
         "test": "vendor/bin/phpunit",
         "test-coverage": "vendor/bin/phpunit --coverage-html coverage"
     },

config/settings.php

@@ -3,7 +3,8 @@
 return [
 
     /*
-     * You can register all the settings classes here.
+     * Each settings class used in your application must be registered, you can
+     * put them (manually) here.
      */
     'settings' => [
 
@@ -16,15 +17,13 @@
     'migrations_path' => database_path('settings'),
 
     /*
-     * When no repository was set for a settings class this repository will be
-     * used for loading and saving settings.
+     * When no repository was set for a settings class the following repository
+     * will be used for loading and saving settings.
      */
     'default_repository' => 'database',
 
     /*
-     * Settings will be stored and loaded from these repositories. There are
-     * two types of repositories: database and Redis. But its always
-     * possible to create your specific types of repositories.
+     * Settings will be stored and loaded from these repositories.
      */
     'repositories' => [
         'database' => [
@@ -40,9 +39,19 @@
     ],
 
     /*
-     * When the package discovers a setting with a type other than the PHP built
-     * in types, it should be cast. These casts will automatically cast types
-     * when they occur in a settings class.
+     * The contents of settings classes can be cached through your application,
+     * settings will be stored within a provided Laravel store and can have an
+     * additional prefix.
+     */
+    'cache' => [
+        'enabled' => env('SETTINGS_CACHE_ENABLED', false),
+        'store' => null,
+        'prefix' => null,
+    ],
+
+    /*
+     * These global casts will be automatically used whenever a property within
+     * your settings class isn't a default PHP type.
      */
     'global_casts' => [
         DateTimeInterface::class => Spatie\LaravelSettings\SettingsCasts\DateTimeInterfaceCast::class,
@@ -59,8 +68,8 @@
     ],
 
     /*
-     * When in production, it is advised to cache the automatically discovered
-     * and registered setting classes will be cached in this path.
+     * Automatically discovered settings classes can be cached so they don't
+     * need to be searched each time the application boors up.
      */
-    'cache_path' => storage_path('app/laravel-settings'),
+    'discovered_settings_cache_path' => storage_path('app/laravel-settings'),
 ];

psalm.xml

@@ -13,6 +13,21 @@
     </projectFiles>
 
     <issueHandlers>
+        <UnusedClosureParam>
+            <errorLevel type="suppress">
+                <file name="src/SettingsMapper.php"/>
+            </errorLevel>
+        </UnusedClosureParam>
+        <InvalidReturnType>
+            <errorLevel type="suppress">
+                <file name="src/SettingsConfig.php"/>
+            </errorLevel>
+        </InvalidReturnType>
+        <InvalidReturnStatement>
+            <errorLevel type="suppress">
+                <file name="src/SettingsConfig.php"/>
+            </errorLevel>
+        </InvalidReturnStatement>
     </issueHandlers>
 
     <plugins>

src/Console/CacheDiscoveredSettingsCommand.php

@@ -17,9 +17,11 @@ public function handle(SettingsContainer $container, Filesystem $files): void
     {
         $this->info('Caching registered settings...');
 
-        $container->getSettingClasses()
+        $container
+            ->clearCache()
+            ->getSettingClasses()
             ->pipe(function (Collection $settingClasses) use ($files) {
-                $cachePath = config('settings.cache_path');
+                $cachePath = config('settings.discovered_settings_cache_path');
 
                 $files->makeDirectory($cachePath, 0755, true, true);
 

src/Console/ClearCachedSettingsCommand.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Spatie\LaravelSettings\Console;
+
+use Illuminate\Console\Command;
+use Spatie\LaravelSettings\SettingsCache;
+
+class ClearCachedSettingsCommand extends Command
+{
+    protected $signature = 'settings:clear-cache';
+
+    protected $description = 'Clear cached settings';
+
+    public function handle(SettingsCache $settingsCache): void
+    {
+        $settingsCache->clear();
+
+        $this->info('Cached settings cleared!');
+    }
+}

src/Console/ClearDiscoveredSettingsCacheCommand.php

@@ -13,7 +13,7 @@ class ClearDiscoveredSettingsCacheCommand extends Command
 
     public function handle(Filesystem $files): void
     {
-        $files->delete(config('settings.cache_path') . '/settings.php');
+        $files->delete(config('settings.discovered_settings_cache_path') . '/settings.php');
 
         $this->info('Cached discovered settings cleared!');
     }

src/Events/LoadingSettings.php

@@ -2,18 +2,17 @@
 
 namespace Spatie\LaravelSettings\Events;
 
-use Spatie\LaravelSettings\Support\SettingsPropertyDataCollection;
+use Illuminate\Support\Collection;
 
 class LoadingSettings
 {
     public string $settingsClass;
 
-    public SettingsPropertyDataCollection $properties;
+    public Collection $properties;
 
-    public function __construct(string $settingsClass, SettingsPropertyDataCollection $properties)
+    public function __construct(string $settingsClass, Collection $properties)
     {
         $this->settingsClass = $settingsClass;
-
         $this->properties = $properties;
     }
 }