Laravel Settings Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require yazan/laravel-settings
   php artisan vendor:publish --provider="Yazan\Settings\SettingsServiceProvider"
   php artisan migrate
   

   • Publishes the migration and config files to config/settings.php.

2. Define Settings: Add settings to config/settings.php:

   'general' => [
       'site_name' => 'My App',
       'maintenance_mode' => false,
   ],
   

3. Access Settings: Retrieve a single setting:

   use Yazan\Settings\Facades\Setting;
   $siteName = Setting::get('general.site_name');
   

   Or fetch all general settings:

   $settings = Setting::getAll('general');
   

4. First Use Case: Use in a controller to dynamically render a site header:

   public function showHomepage()
   {
       $siteName = Setting::get('general.site_name');
       return view('home', compact('siteName'));
   }
   

Implementation Patterns

Core Workflows

1. Model-Specific Settings: Attach settings to a model (e.g., User):

   // Define in config/settings.php
   'user' => [
       'default_avatar' => 'avatar-default.png',
   ],
   

   Access via model instance:

   $user = User::find(1);
   $avatar = $user->settings('default_avatar'); // Returns 'avatar-default.png'
   

2. Dynamic Configuration: Override settings per environment or tenant:

   // In a service provider
   Setting::set('general.site_name', 'Dev Environment');
   

3. Validation: Validate settings during updates:

   use Yazan\Settings\Rules\ValidSetting;
   $request->validate([
       'general.site_name' => ['required', new ValidSetting('general.site_name')],
   ]);
   

4. Caching: Cache settings globally (enabled by default in config):

   // Disable caching for a specific setting
   Setting::set('general.site_name', 'New Name', false);
   

Integration Tips

• Blade Directives: Create a custom Blade directive for concise access:

  Blade::directive('setting', function ($key) {
      return "<?php echo \\Yazan\\Settings\Facades\\Setting::get('{$key}'); ?>";
  });
  

  Usage:

  <title>@setting('general.site_name')</title>
  

• Event Listeners: Trigger actions when settings change:

  Setting::set('general.maintenance_mode', true);
  // Dispatch event: SettingUpdated
  

• API Responses: Expose settings via API:

  return response()->json(['site_name' => Setting::get('general.site_name')]);
  

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If manually editing the settings table, ensure the key column is unique (enforced by the migration).
   • Fix: Run php artisan migrate:fresh if conflicts arise.

2. Caching Issues:

   • Settings cached for 24 hours by default. Clear cache manually if updates don’t reflect:

     php artisan cache:clear
     

   • Tip: Use Setting::set(..., false) to bypass caching for testing.

3. Model Binding:

   • Model-specific settings require the model to implement Yazan\Settings\Contracts\HasSettings:

     use Yazan\Settings\Contracts\HasSettings;
     class User implements HasSettings {}
     

   • Gotcha: Forgetting this trait causes settings() method to fail silently.

4. Key Naming:

   • Use dot notation (e.g., general.site_name) for nested settings. Avoid spaces or special characters.
   • Tip: Validate keys with Setting::isValidKey('general.site_name').

5. Mass Assignment:

   • Directly inserting into the settings table bypasses validation. Use Setting::set() or Setting::update() instead.

Debugging

• Check Existence: Verify a setting exists before accessing:

  if (Setting::has('general.site_name')) {
      $name = Setting::get('general.site_name');
  }
  

• Log Missing Keys: Enable debug mode in config/settings.php:

  'debug' => env('APP_DEBUG', false),
  

  Missing keys will log warnings.

• Database Inspection: Inspect the settings table directly:

  SELECT * FROM settings WHERE `key` LIKE 'general.%';
  

Extension Points

1. Custom Storage: Override the default database storage by binding a custom repository:

   $settings = new \Yazan\Settings\Repositories\CustomSettingsRepository();
   $this->app->bind(\Yazan\Settings\Contracts\SettingsRepository::class, function () use ($settings) {
       return $settings;
   });
   

2. Encrypted Settings: Encrypt sensitive settings (e.g., API keys) using Laravel’s encryption:

   $encryptedValue = Setting::encrypt('general.api_key', 'super-secret-key');
   $decryptedValue = Setting::decrypt($encryptedValue);
   

3. Setting Groups: Group settings by functionality (e.g., payment, analytics) and use middleware to restrict access:

   public function handle($request, Closure $next)
   {
       if (!$request->user()->can('manage_payment_settings')) {
           abort(403);
       }
       return $next($request);
   }
   

4. Versioning: Track setting changes over time by adding a created_at and updated_at column to the settings table and querying historical values:

   $history = DB::table('settings')
       ->where('key', 'general.site_name')
       ->orderBy('updated_at', 'desc')
       ->get();