Abstract Theme Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer in your Laravel project (or Symfony if applicable):

   composer require bloghoven/abstract-theme-bundle
   

   Register the bundle in config/app.php (Laravel) or bundles.php (Symfony):

   'providers' => [
       // ...
       Bloghoven\AbstractThemeBundle\AbstractThemeServiceProvider::class,
   ],
   

2. Publish Configuration Publish the default config (if available) and adjust as needed:

   php artisan vendor:publish --provider="Bloghoven\AbstractThemeBundle\AbstractThemeServiceProvider"
   

   (Note: Verify if the package includes a publishable config file.)

3. First Use Case: Theme Switching Use the bundle’s facade or service to switch themes dynamically:

   use Bloghoven\AbstractThemeBundle\Facades\Theme;
   
   // Set a theme (e.g., 'dark', 'light', or custom)
   Theme::set('dark');
   
   // Retrieve current theme
   $currentTheme = Theme::get();
   

4. Theme Assets Check the package’s documentation for how to load theme-specific assets (CSS/JS). Example:

   // Assume the bundle provides a helper for theme-aware assets
   Theme::asset('styles.css'); // Outputs: /themes/dark/styles.css
   

Implementation Patterns

1. Theme-Aware Blade Directives

Extend Blade templates to dynamically load theme-specific content:

// In a service provider (e.g., AppServiceProvider)
Blade::directive('theme', function ($expression) {
    return "<?php echo \\Bloghoven\\AbstractThemeBundle\Facades\\Theme::wrap('{$expression}'); ?>";
});

Usage in Blade:

@theme('partials/header')

2. Middleware for Theme Persistence

Use middleware to persist theme preferences (e.g., via cookies or sessions):

namespace App\Http\Middleware;

use Bloghoven\AbstractThemeBundle\Facades\Theme;
use Closure;

class SetThemeFromCookie
{
    public function handle($request, Closure $next)
    {
        $theme = $request->cookie('theme_preference');
        if ($theme) {
            Theme::set($theme);
        }
        return $next($request);
    }
}

Register in app/Http/Kernel.php:

protected $middleware = [
    // ...
    \App\Http\Middleware\SetThemeFromCookie::class,
];

3. Dynamic Theme Switching via API

Expose an API endpoint to toggle themes (useful for SPAs or mobile apps):

Route::post('/api/theme', function (Request $request) {
    $theme = $request->validate(['theme' => 'required|string']);
    Theme::set($theme['theme']);
    return response()->json(['success' => true]);
});

4. Theme-Specific Views

Organize views by theme (e.g., resources/views/themes/dark/partials/header.blade.php). Use a helper to resolve the correct path:

// Example helper in AbstractThemeServiceProvider
public function boot()
{
    view()->macro('theme', function ($view, $theme = null) {
        $theme = $theme ?? Theme::get();
        return view("themes.{$theme}.{$view}");
    });
}

Usage:

@theme('partials/header')

5. Fallback Themes

Implement a fallback chain for missing themes:

Theme::set('custom-theme', ['fallback' => ['dark', 'light']]);

Gotchas and Tips

Pitfalls

1. No Built-in Configuration The package lacks a config/abstract-theme.php file (as of now). Expect to define defaults manually in a service provider:

   config(['abstract-theme.default' => 'light']);
   

2. Asset Path Assumptions The package may assume themes are stored in public/themes/{theme}/. Verify and adjust paths if needed:

   // Override asset resolution in the service provider
   Theme::setAssetPath(function ($theme, $asset) {
       return "/custom-path/{$theme}/{$asset}";
   });
   

3. Caching Headaches If using Blade caching (php artisan view:cache), clear it after theme changes:

   php artisan view:clear
   

4. Namespace Collisions The package’s Theme facade might conflict with other Theme classes. Use aliases:

   'aliases' => [
       'AbstractTheme' => Bloghoven\AbstractThemeBundle\Facades\Theme::class,
   ],
   

Debugging Tips

1. Log Theme Switches Add logging to track theme changes:

   Theme::set('dark', function ($theme) {
       \Log::info("Theme switched to: {$theme}");
   });
   

2. Verify Theme Existence Check if a theme exists before switching:

   if (!Theme::exists('custom-theme')) {
       Theme::set('light'); // Fallback
   }
   

3. Inspect Published Config If the package publishes config, inspect it for undocumented options:

   php artisan config:dump
   

Extension Points

1. Custom Theme Storage Override the storage backend (e.g., database, Redis) by binding a ThemeStorage interface:

   $this->app->bind(
       Bloghoven\AbstractThemeBundle\Contracts\ThemeStorage::class,
       App\Services\CustomThemeStorage::class
   );
   

2. Theme Events Listen for theme changes via events (if the package supports them):

   event(new \Bloghoven\AbstractThemeBundle\Events\ThemeSwitched($oldTheme, $newTheme));
   

3. Theme Validation Add validation rules for allowed themes:

   Theme::set('dark', ['validator' => function ($theme) {
       return in_array($theme, ['light', 'dark', 'custom']);
   }]);
   

4. Internationalization (i18n) If themes include translations, integrate with Laravel’s localization:

   // Example: Load theme-specific locale
   app()->setLocale(Theme::getLocale());