Laratheme Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require codersfree/laratheme
   

   Publish the package configuration and migrations:

   php artisan vendor:publish --provider="CodersFree\Laratheme\LarathemeServiceProvider" --tag="config"
   php artisan vendor:publish --provider="CodersFree\Laratheme\LarathemeServiceProvider" --tag="migrations"
   php artisan migrate
   

2. Basic Configuration Edit config/laratheme.php to define:

   • Default theme
   • Theme directories (e.g., resources/themes)
   • Theme switch middleware

3. Create Your First Theme

   • Place a theme folder (e.g., resources/themes/default) with:
     • views/ (Blade templates)
     • assets/ (CSS/JS)
     • config.php (theme-specific settings)

4. First Use Case: Switching Themes

   // In a controller or middleware
   \CodersFree\Laratheme\Facades\Laratheme::setTheme('new-theme-name');
   

Implementation Patterns

Theme Switching Workflows

1. User-Based Theme Selection

   // Middleware to set theme per user
   public function handle($request, Closure $next) {
       $theme = auth()->user()->theme ?? config('laratheme.default');
       Laratheme::setTheme($theme);
       return $next($request);
   }
   

2. Dynamic Theme Switching via API

   // API endpoint to change theme
   Route::post('/theme/switch', function (Request $request) {
       $request->validate(['theme' => 'required|exists:themes,name']);
       Laratheme::setTheme($request->theme);
       return response()->json(['success' => true]);
   });
   

Asset Management

1. Theme-Specific Assets

   // In Blade templates
   <link href="{{ Laratheme::asset('css/style.css') }}" rel="stylesheet">
   <script src="{{ Laratheme::asset('js/app.js') }}"></script>
   

2. Fallback Assets

   // Use a fallback theme if the current theme lacks an asset
   <link href="{{ Laratheme::asset('css/style.css', 'fallback-theme') }}" rel="stylesheet">
   

View Overrides

1. Theme-Specific Views

   // Blade template will automatically look in `resources/themes/[current-theme]/views/`
   @extends('layouts.app')
   

2. Partial Overrides

   // Override a partial (e.g., `header.blade.php`) in a specific theme
   @includeIf(Laratheme::viewExists('partials.header'), 'partials.header')
   

Configuration

1. Theme-Specific Config

   // Access theme config
   $darkMode = Laratheme::config('dark_mode', false);
   

2. Merge Global + Theme Config

   // In a service provider
   $config = array_merge(
       config('app'),
       Laratheme::config()
   );
   

Gotchas and Tips

Pitfalls

1. Asset Paths

   • Issue: Assets not loading due to incorrect paths.
   • Fix: Always use Laratheme::asset() instead of hardcoding paths. Verify theme_assets_path in config.

2. View Caching

   • Issue: Cached views may not reflect theme changes.
   • Fix: Clear view cache after theme changes:

     php artisan view:clear
     

3. Middleware Order

   • Issue: Theme-switching middleware not executing.
   • Fix: Ensure LarathemeMiddleware runs before ShareErrorsFromSession and StartSession in app/Http/Kernel.php.

4. Theme Naming Conflicts

   • Issue: Theme names conflicting with Laravel's reserved words (e.g., config, routes).
   • Fix: Prefix theme folders (e.g., theme_dark, theme_light).

Debugging Tips

1. Check Active Theme

   dd(Laratheme::getActiveTheme());
   

2. Verify Theme Exists

   if (!Laratheme::themeExists('my-theme')) {
       abort(404, 'Theme not found');
   }
   

3. Log Theme-Specific Errors

   try {
       Laratheme::view('non-existent-file');
   } catch (\Exception $e) {
       \Log::error("Theme error in [{$theme}]: " . $e->getMessage());
   }
   

Extension Points

1. Custom Theme Storage Override the default theme storage (e.g., database, cache) by binding a custom ThemeRepository:

   $this->app->bind(
       \CodersFree\Laratheme\Contracts\ThemeRepository::class,
       \App\Services\CustomThemeRepository::class
   );
   

2. Theme Events Listen for theme-switch events:

   Laratheme::onThemeSwitched(function ($oldTheme, $newTheme) {
       \Log::info("Switched from {$oldTheme} to {$newTheme}");
   });
   

3. Dynamic Theme Loading Load themes from external sources (e.g., S3, API) by extending ThemeLoader:

   class S3ThemeLoader extends \CodersFree\Laratheme\Services\ThemeLoader {
       public function load($theme) {
           // Custom logic to fetch theme from S3
       }
   }