Laravel Themer Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require alizharb/laravel-themer
   php artisan themer:install
   

   • Runs migrations, publishes config, and sets up default theme structure.
   • New in v1.3.0: Automatically initializes .gitignore files and theme.json hooks during installation.

2. Default Theme Structure

   • Themer creates a themes/ directory in your resources/ folder.
   • Updated structure with theme.json (new in v1.3.0):

     resources/themes/
     ├── default/          # Default theme
     │   ├── views/        # Blade templates
     │   ├── assets/       # CSS/JS
     │   ├── config.php    # Theme-specific config
     │   └── theme.json    # New: Theme metadata & hooks (v1.3.0)
     └── custom/           # Your custom themes
     

3. First Use Case: Interactive Theme Creation

   • Launch the new wizard:

     php artisan themer:make
     

   • Follow prompts to create a theme with auto-generated .gitignore and theme.json.

4. First Blade Template with Vite

   • Use native Vite integration (no symlinks):

     @vite(['resources/themes/default/assets/css/app.css'])
     

   • New in v1.3.0: Themes now support standard @vite tags without legacy workarounds.

Implementation Patterns

1. Modular Theme Integration

• Zero-Config Modularity

  • Themes auto-discover in resources/themes/ (custom paths configurable).
  • Each theme includes theme.json (v1.3.0) for metadata and hooks:

    {
      "name": "custom.my-theme",
      "hooks": {
        "after_activate": ["php artisan db:seed --class=EcommerceSeeder"]
      }
    }
    

• Theme-Specific Assets with Vite

  • Publish assets via:

    php artisan themer:publish --theme=custom.my-theme
    

  • Use @vite directly in Blade (native Vite support in v1.3.0):

    @vite(['resources/themes/custom/my-theme/assets/js/app.js'])
    

2. Dynamic Theme Switching

• Middleware-Based (with Preview Support)

  // app/Http/Middleware/SwitchTheme.php
  public function handle(Request $request, Closure $next) {
      $theme = $request->user()->preferred_theme ?? 'default';
      if ($request->query('preview_theme')) {
          Themer::previewTheme($request->query('preview_theme')); // New in v1.3.0
      } else {
          Themer::setTheme($theme);
      }
      return $next($request);
  }
  

  • New in v1.3.0: PreviewTheme middleware for secure theme previews via ?preview_theme=slug.

• Livewire Integration

  public function mount() {
      Themer::setTheme('dark');
      $this->dispatch('theme-switched')->toOthers();
  }
  

3. Theme Configuration

• Global vs. Theme-Specific Config
  • Override in config/themer.php:

    'themes' => [
        'custom.my-theme' => [
            'assets_path' => 'themes/custom/my-theme/assets',
            'config' => ['primary_color' => '#3b82f6'],
            'hooks' => ['after_activate' => ['php artisan optimize']] // v1.3.0
        ],
    ],
    

  • Access in Blade:

    <div style="color: {{ config('themer.themes.custom.my-theme.config.primary_color') }};">
    

4. View Overrides

• Fallback Chain

  • Themer checks: active_theme → default → vendor/themer.
  • Override views by placing them in the active theme’s views/ directory.

• Partial Overrides with Vite

  @push('themer-scripts')
      @vite(['resources/themes/custom/my-theme/assets/js/partial.js'])
  @endpush
  

5. Livewire 4 + Vite Support

• Theme-Aware Components

  @themerComponent('theme-aware-component', ['prop' => 'value'])
  

  • Components auto-detect the active theme’s Vite assets.

• Dynamic Theme Switching

  public function switchTheme(string $theme) {
      Themer::setTheme($theme);
      $this->dispatch('theme-switched')->toOthers();
  }
  

Gotchas and Tips

Pitfalls

1. Asset Path Conflicts

   • Fix: Use @vite directly (v1.3.0 removes symlink legacy). Verify paths with:

     php artisan themer:publish --theme=NAME
     

2. Caching Issues

   • New in v1.3.0: Zero-IO production cache (bootstrap/cache/themes.php). Clear only when themes change:

     php artisan theme:cache
     

3. Livewire Hydration Mismatches

   • Set the theme before Livewire mounts (use middleware).

4. Namespace Collisions

   • Avoid reserved names (e.g., admin). Use prefixes like custom.my-theme/.

5. Theme Hooks (v1.3.0)

   • Commands in theme.json must be valid Artisan commands. Test locally first.

Debugging

• Check Active Theme

  php artisan themer:list
  

  • Lists all themes + active/preview themes (v1.3.0).

• Log Theme Switches Enable debug mode:

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

• Verify View Resolution

  Themer::resolveView('path.to.view');
  

• New in v1.3.0: Linting

  php artisan theme:lint custom.my-theme
  

  • Runs laravel-pint + NPM formatters scoped to the theme.

Extension Points

1. Custom Theme Resolvers

   Themer::extend(function ($theme) {
       return ThemeResolver::resolve($theme);
   });
   

2. Theme Events (v1.3.0)

   • Listen to lifecycle hooks:

     Themer::on('theme.activated', function ($theme) {
         Log::info("Activated: {$theme}");
     });
     

3. Asset Pipeline Hooks

   • Modify Vite paths:

     Themer::macro('assetPath', function ($path) {
         return str_replace('public/', 'themed/', $path);
     });
     

4. Dynamic Theme Loading

   • Load themes from S3:

     Themer::addThemeSource(new S3ThemeSource());
     

Performance Tips

• Precompile Themes (v1.3.0)

  php artisan theme:cache
  

  • Generates bootstrap/cache/themes.php for instant boot.

• Lazy-Load Assets

  @if(Themer::isTheme('custom.my-theme'))
      @vite(['resources/themes/custom/my-theme/assets/js/app.js'])
  @endif
  

• Git Workspace Sync (v1.3.0)

  • .gitignore auto-generated in new themes. Exclude:

    /themes/*/vendor/
    /themes/*/node_modules/
    

New in v1.3.0: Safe Mode Fallback

• If a theme’s ThemeServiceProvider crashes, the system silently falls back to the default theme. No more fatal errors during boot.

Upgrade Path

• Run the automated upgrade tool:

  php artisan theme:upgrade
  

  • Injects missing .gitignore and initializes theme.json hooks.