Laravel Model Settings Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require lukasss93/laravel-model-settings
   

2. Choose a storage method and apply the appropriate trait to your model:

   • Field-based (JSON column):

     php artisan model-settings:model-settings-field User
     

     Add to your model:

     use Lukasss93\ModelSettings\Traits\HasSettingsField;
     class User extends Model { use HasSettingsField; }
     

   • Table-based (dedicated table):

     php artisan model-settings:model-settings-table User
     

     Add to your model:

     use Lukasss93\ModelSettings\Traits\HasSettingsTable;
     class User extends Model { use HasSettingsTable; }
     

   • Redis-based (caching):

     use Lukasss93\ModelSettings\Traits\HasSettingsRedis;
     class User extends Model { use HasSettingsRedis; }
     

3. First use case: Set and retrieve a setting:

   $user = User::first();
   $user->settings()->set('theme', 'dark'); // Set
   $theme = $user->settings()->get('theme'); // Retrieve
   

Key Configuration

• Field/table name: Customize via .env (MODEL_SETTINGS_FIELD_NAME or MODEL_SETTINGS_TABLE_NAME).
• Persistence: Toggle auto-save for field-based settings with $persistSettings (default: true).

Implementation Patterns

Core Workflows

1. CRUD Operations

• Single setting:

  $user->settings()->set('key', 'value');
  $value = $user->settings()->get('key', 'default');
  $user->settings()->delete('key');
  

• Bulk operations:

  $user->settings()->setMultiple(['key1' => 'val1', 'key2' => 'val2']);
  $values = $user->settings()->getMultiple(['key1', 'key2'], 'default');
  $user->settings()->deleteMultiple(['key1', 'key2']);
  

• Full reset:

  $user->settings()->clear();
  

2. Default Values & Validation

Define defaults and rules in your model:

public function defaultSettings(): array {
    return ['theme' => 'light', 'notifications' => true];
}

public function settingsRules(): array {
    return [
        'theme' => 'in:light,dark',
        'notifications' => 'boolean',
    ];
}

• Auto-apply defaults on model creation if $initSettings = true.

3. Custom Method Names

Override the settings() method alias:

public $invokeSettingsBy = 'configurations';
// Now use: $user->configurations()->get('key')

4. Conditional Checks

if ($user->settings()->has('theme')) {
    // Setting exists
}
if ($user->settings()->empty()) {
    // No settings exist
}

Integration Tips

• Events: Listen to settings.stored or settings.retrieved via Laravel events.
• Observers: Extend model observers to log setting changes.
• APIs: Useful for dynamic feature flags or user preferences in RESTful APIs.
• Testing: Mock settings with:

  $user->settings()->shouldReceive('get')->andReturn('mocked_value');
  

Performance Considerations

• Field-based: Fast for small settings (JSON serialization overhead).
• Table-based: Better for large/complex settings (cached by default).
• Redis-based: Ideal for high-read scenarios (e.g., feature flags).

Gotchas and Tips

Pitfalls

1. Migration Order:

   • Run model-settings:model-settings-field/table before migrating the model table.
   • Field-based: Ensure the JSON column exists before using HasSettingsField.

2. Validation Timing:

   • Rules in settingsRules() are applied only during set(), apply(), or update().
   • get() bypasses validation.

3. Default Initialization:

   • $initSettings = true applies defaults only once (on first save if using field-based storage).
   • Override defaultSettings() to reset defaults dynamically.

4. Redis Cache Invalidation:

   • Redis settings are not auto-synced to other storage backends. Use settings()->flush() to force sync.

5. Nested Arrays:

   • Flattened automatically (e.g., ['user' => ['name' => 'John']] becomes 'user.name').
   • Access nested values with dot notation: get('user.name').

Debugging Tips

• Check storage backend:

  $user->settings()->getStorage(); // Returns 'field', 'table', or 'redis'
  

• Validate JSON field:

  php artisan db:show User settings
  

• Clear cached settings (table/redis):

  $user->settings()->flush();
  

Extension Points

1. Custom Storage: Implement Lukasss93\ModelSettings\Contracts\SettingsStorage for alternative backends (e.g., DynamoDB).

2. Event Hooks: Publish the config and extend:

   ModelSettings::extend(function ($model) {
       $model->settings()->listen('stored', fn() => Log::info('Setting saved'));
   });
   

3. Dynamic Rules: Use closures in settingsRules() for runtime validation:

   'max_posts' => function ($value, $attribute) {
       return $value <= auth()->user()->plan->limit;
   }
   

4. Fallback Logic: Chain defaults in get():

   $value = $user->settings()->get('theme', 'light', 'dark');
   

Configuration Quirks

• Environment Variables:
  • MODEL_SETTINGS_PERSISTENT: Overrides $persistSettings globally.
  • MODEL_SETTINGS_CACHE_MINUTES: Adjusts Redis/table cache TTL (default: 60).
• Config File: Publish with:

  php artisan vendor:publish --tag="model-settings-config"
  

  Customize settings_field_name, settings_table_name, and storage (e.g., redis).

Laravel-Specific Notes

• Model Binding: Settings persist across requests (unlike session data).
• Replicas: Field/table-based settings replicate automatically. Redis requires manual setup.
• Queues: Use settings()->apply() with queued jobs for async updates:

  User::find($id)->settings()->apply($settings)->save();