Module Settings Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cvepdb-cms/module-settings
   

   Publish the package configuration (if needed):

   php artisan vendor:publish --provider="Cvepdb\ModuleSettings\ModuleSettingsServiceProvider" --tag="config"
   

2. Basic Usage Register a settings module in your service provider:

   use Cvepdb\ModuleSettings\Facades\ModuleSettings;
   
   ModuleSettings::register('my_module', [
       'name' => 'My Module Settings',
       'fields' => [
           'setting_key' => [
               'type' => 'text',
               'label' => 'Setting Label',
               'default' => 'default_value',
           ],
       ],
   ]);
   

3. First Use Case Retrieve and update settings in a controller:

   // Get settings
   $settings = ModuleSettings::get('my_module');
   
   // Update settings
   ModuleSettings::set('my_module', ['setting_key' => 'new_value']);
   

Implementation Patterns

Workflows

1. Dynamic Module Registration Register settings modules dynamically (e.g., via service providers or package bootstrapping):

   ModuleSettings::register('dynamic_module', [
       'fields' => [
           'dynamic_field' => [
               'type' => 'checkbox',
               'label' => 'Enable Feature',
           ],
       ],
   ]);
   

2. Field Validation Define validation rules for settings fields:

   ModuleSettings::register('validated_module', [
       'fields' => [
           'email' => [
               'type' => 'email',
               'label' => 'Admin Email',
               'rules' => 'required|email',
           ],
       ],
   ]);
   

3. Grouped Settings Organize settings into logical groups (e.g., tabs or sections):

   ModuleSettings::register('grouped_module', [
       'groups' => [
           'general' => [
               'label' => 'General Settings',
               'fields' => [...],
           ],
           'advanced' => [
               'label' => 'Advanced',
               'fields' => [...],
           ],
       ],
   ]);
   

4. Integration with Admin Panels Use the ModuleSettings::render() helper to generate a settings form in your admin panel:

   return view('admin.settings', [
       'form' => ModuleSettings::render('my_module'),
   ]);
   

5. Event-Based Updates Listen for settings changes via events:

   ModuleSettings::register('event_module', [...]);
   
   event(new \Cvepdb\ModuleSettings\Events\SettingsUpdated('event_module'));
   

Integration Tips

• Database Storage The package defaults to storing settings in the database. Ensure your settings table exists (or migrate it):

  php artisan migrate
  

  Customize the table name in config/module-settings.php if needed.

• Caching Cache settings for performance:

  ModuleSettings::setCacheDuration(60); // Cache for 60 minutes
  

• Local Overrides Override settings locally (e.g., for development):

  ModuleSettings::set('my_module', [], true); // Force local override
  

• API Access Expose settings via API routes:

  Route::get('/api/settings/{module}', function ($module) {
      return ModuleSettings::get($module);
  });
  

Gotchas and Tips

Pitfalls

1. Case Sensitivity Module names are case-sensitive. Ensure consistency when registering and retrieving settings:

   // Correct
   ModuleSettings::register('my_module', [...]); // Register
   ModuleSettings::get('my_module');            // Retrieve
   
   // Incorrect (will return null)
   ModuleSettings::get('My_Module');
   

2. Field Type Mismatches Invalid field types (e.g., 'type' => 'nonexistent') will throw exceptions. Use supported types:

   • text, textarea, email, number, checkbox, select, radio, color, date.

3. Missing Defaults Fields without default values will return null if not previously set. Explicitly define defaults:

   'fields' => [
       'required_field' => [
           'type' => 'text',
           'default' => '', // Explicit empty string
       ],
   ],
   

4. Concurrent Updates Race conditions can occur when multiple requests update settings simultaneously. Use transactions:

   DB::transaction(function () {
       ModuleSettings::set('my_module', $newSettings);
   });
   

5. Configuration Overrides Published config (config/module-settings.php) can be overridden by environment-specific files (e.g., .env or config/module-settings.php in config/). Ensure your overrides are intentional.

Debugging

1. Log Settings Enable debug logging to inspect settings:

   \Log::debug('Module Settings:', ModuleSettings::all());
   

2. Validate Registration Check if a module is registered before accessing it:

   if (ModuleSettings::has('my_module')) {
       $settings = ModuleSettings::get('my_module');
   } else {
       \Log::error('Module "my_module" not registered!');
   }
   

3. Clear Cache If settings aren’t updating, clear the cache:

   php artisan cache:clear
   php artisan config:clear
   

Extension Points

1. Custom Field Types Extend the package by adding custom field types:

   ModuleSettings::extend('custom_type', function ($value, $field) {
       return \App\CustomField::process($value, $field);
   });
   

2. Hooks Use the settings.saving and settings.saved events to intercept updates:

   \Event::listen('settings.saving', function ($module, $settings) {
       // Modify settings before save
   });
   

3. Storage Backends Replace the default database storage with a custom backend (e.g., Redis, S3):

   ModuleSettings::setStorage(new \App\CustomSettingsStorage());
   

4. Localization Localize field labels and placeholders:

   'fields' => [
       'name' => [
           'type' => 'text',
           'label' => 'app::settings.name', // Language line
       ],
   ],
   

5. Authorization Restrict access to settings modules via middleware or gates:

   ModuleSettings::authorize('my_module', function () {
       return \Auth::user()->can('manage-settings');
   });