Laravel User Preferences Laravel Package

Getting Started

Start by installing the package and publishing its assets:

composer require robtrehy/laravel-user-preferences  
php artisan vendor:publish --provider="RobTrehy\LaravelUserPreferences\UserPreferencesServiceProvider" --tag="config"  
php artisan vendor:publish --provider="RobTrehy\LaravelUserPreferences\UserPreferencesServiceProvider" --tag="migrations" && php artisan migrate  

This creates config/user-preferences.php, adds a preferences JSON column to your users table (or your custom table/column), and enables caching by default.

The simplest first use case is managing theme or UI preferences for the current user:

// Set a preference (e.g., dark mode)  
UserPreferences::set('theme', 'dark');  

// Retrieve it  
$theme = UserPreferences::get('theme'); // 'dark'  

// Default fallback via config  
UserPreferences::get('notifications_enabled'); // falls back to config 'defaults'

Implementation Patterns

• Per-Request Caching: Preferences for the current user are cached per-request (via static $preferencesCache) and optionally via Laravel’s cache driver. Avoids repeated DB hits in long requests (e.g., admin dashboards).
• User-Specific Workflows:

  // Admin panel: set preferences for *another* user (e.g., bulk user onboarding)  
  UserPreferences::setForUser('locale', 'en-GB', 42); // user ID  
  UserPreferences::setForUser('sidebar_collapsed', true, $userModel);  
  

• Seamless Defaults: Define fallbacks in config/user-preferences.php so partial preferences work out-of-the-box:

  'defaults' => [
      'theme' => 'light',
      'pagination' => 25,
      'timezone' => 'UTC'
  ]
  

• Stateful UI Components: Use preferences for UI state:

  // In a Livewire component  
  public function mount(): void  
  {  
      $this->theme = UserPreferences::get('theme', 'light'); // default not needed; `get()` handles fallback  
      $this->sidebarOpen = ! UserPreferences::get('sidebar_collapsed');  
  }  
  

• Resetting Preferences: Reset user-specific or default preferences:

  UserPreferences::reset('theme'); // delete per-user value → falls back to default  
  UserPreferences::setDefaultPreferences(); // wipe all per-user overrides  
  

Gotchas and Tips

• null Handling: Historically fragile (json_decode(null) warnings). Ensure you’re on ≥4.1.1 — recent hotfixes (4.1.1–4.1.3) robustly handle null database columns.
• Cache Invalidation: Since preferences are cached, changes made outside the web request (e.g., queued jobs, Tinker) won’t auto-refresh for the current user. Force-refresh by calling UserPreferences::forgetCache() (internal) or clearing Laravel’s cache if needed.
• Column Constraints: The preferences column must be TEXT or JSON (not VARCHAR). Laravel’s migrations default text() — verify your generated migration uses nullable()->text() or json().
• Testing Tip: In feature tests, mock Auth::user() before calling preference methods to avoid ambiguous user resolution:

  $user = User::factory()->create();  
  $this->actingAs($user);  
  UserPreferences::set('demo', true); // now targets `$user`  
  $this->assertEquals('light', UserPreferences::get('nonexistent', 'light')); // safe with fallback  
  

• Customization Extension: Override the default table/column in config/user-preferences.php — ideal if using a separate user_preferences table for auditability:

  'database' => [
      'table' => 'user_preferences',
      'column' => 'payload',
      'primary_key' => 'user_id'
  ]
  

• Avoid Over-Use: This package stores user preferences — not application-level or shared config. Keep site-wide defaults in .env/config files instead.