Theme Lumen Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require cvepdb-cms/theme-lumen
   

   Ensure your Laravel/Lumen project meets the package's PHP version requirements (check composer.json of the package).

2. Publish Assets

   php artisan vendor:publish --provider="Cvepdb\ThemeLumen\ThemeLumenServiceProvider" --tag=public
   

   This copies the Lumen theme assets (CSS, JS, views) to public/vendor/theme-lumen.

3. First Use Case: Basic Theme Integration

   • Add the theme to your config/app.php under providers:

     Cvepdb\ThemeLumen\ThemeLumenServiceProvider::class,
     

   • Register the theme in bootstrap/app.php (Lumen) or AppServiceProvider (Laravel):

     $app->register(\Cvepdb\ThemeLumen\ThemeLumenServiceProvider::class);
     

   • Use the theme in a route or controller:

     return view('theme-lumen::home'); // Assumes views are published to `resources/views/vendor/theme-lumen`
     

Implementation Patterns

1. View Overrides

• Override default theme views by placing them in resources/views/vendor/theme-lumen.
• Example: Copy home.blade.php from the published assets to customize the homepage.

2. Dynamic Theme Switching

• Use middleware to switch themes based on user roles or preferences:

  namespace App\Http\Middleware;
  
  use Closure;
  use Cvepdb\ThemeLumen\Facades\Theme;
  
  class ThemeMiddleware
  {
      public function handle($request, Closure $next)
      {
          Theme::set('lumen'); // Force 'lumen' theme
          return $next($request);
      }
  }
  

• Register middleware in bootstrap/app.php:

  $app->middleware(['theme' => \App\Http\Middleware\ThemeMiddleware::class]);
  

3. Asset Management

• Publish and version assets:

  php artisan vendor:publish --tag=theme-lumen-assets
  

• Include assets in your layout:

  <link rel="stylesheet" href="{{ asset('vendor/theme-lumen/css/theme.css') }}">
  

4. Configuration

• Publish the config file:

  php artisan vendor:publish --tag=theme-lumen-config
  

• Customize in config/theme-lumen.php:

  'default' => 'lumen',
  'paths' => [
      'views' => resource_path('views/vendor/theme-lumen'),
  ],
  

5. Integration with CMS

• Use the theme’s facade to fetch CMS content:

  use Cvepdb\ThemeLumen\Facades\Cms;
  
  $content = Cms::get('homepage');
  return view('theme-lumen::home', compact('content'));
  

Gotchas and Tips

Pitfalls

1. Asset Paths

   • If assets aren’t loading, verify the public/vendor/theme-lumen directory exists and permissions are correct.
   • Clear cached views and config:

     php artisan view:clear
     php artisan config:clear
     

2. View Naming Conflicts

   • Avoid naming custom views the same as the package’s default views (e.g., home.blade.php). Use unique names or prefixes.

3. Lumen vs. Laravel Compatibility

   • The package is optimized for Lumen. In Laravel, ensure the ThemeLumenServiceProvider is registered correctly and that the Theme facade is available globally.

4. Caching Issues

   • Disable caching during development if themes aren’t updating:

     'cache' => [
         'enabled' => env('APP_DEBUG') === false,
     ],
     

     in config/theme-lumen.php.

Debugging Tips

• Check Published Files Verify files were published to public/vendor/theme-lumen and resources/views/vendor/theme-lumen.
• Log Theme Events Enable debug mode in config/theme-lumen.php:

  'debug' => true,
  

  This logs theme-related events to storage/logs/lumen-theme.log.
• Facade Availability If Theme::set() fails, ensure the facade is registered in config/app.php:

  'aliases' => [
      'Theme' => Cvepdb\ThemeLumen\Facades\Theme::class,
  ],
  

Extension Points

1. Custom Directives Extend Blade directives in AppServiceProvider:

   Blade::directive('themeAsset', function ($expression) {
       return "<?php echo asset('vendor/theme-lumen/{$expression}'); ?>";
   });
   

   Usage in views:

   <img src="{{ themeAsset('images/logo.png') }}">
   

2. Theme Events Listen for theme-switch events:

   Theme::on('switch', function ($theme) {
       Log::info("Switched to theme: {$theme}");
   });
   

3. Dynamic Partial Views Load partials dynamically:

   $partial = Theme::partial('header');
   echo $partial;