Lara Base Theme Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require appdezign/lara-base-theme
   

   Publish the theme assets and configuration:

   php artisan vendor:publish --provider="Appdezign\LaraBaseTheme\LaraBaseThemeServiceProvider" --tag="public"
   php artisan vendor:publish --provider="Appdezign\LaraBaseTheme\LaraBaseThemeServiceProvider" --tag="config"
   

2. First Use Case: Basic Theme Integration

   • Register the theme in config/cms.php under themes:

     'themes' => [
         'base' => [
             'name' => 'Base Theme',
             'path' => base_path('vendor/appdezign/lara-base-theme/resources/views'),
             'active' => true,
         ],
     ],
     

   • Use the theme in a Blade template:

     @extends('lara-base-theme::layouts.app')
     @section('content')
         {{ $slot }}
     @endsection
     

3. Key Files to Review

   • config/lara-base-theme.php (default config)
   • resources/views/vendor/lara-base-theme/ (default view structure)
   • docs.laracms.nl/ (official documentation)

Implementation Patterns

Core Workflows

1. Theme Inheritance Extend the base theme by creating a custom theme in resources/themes/your-theme:

   php artisan vendor:publish --tag="lara-base-theme-views" --provider="Appdezign\LaraBaseTheme\LaraBaseThemeServiceProvider"
   

   Override views by placing them in resources/themes/your-theme/views/.

2. Dynamic Layouts Use the @layout directive to switch layouts dynamically:

   @layout('lara-base-theme::layouts.admin')
   

3. Asset Management Compile assets via Laravel Mix or Vite. The package includes:

   • SASS preprocessing (resources/sass/)
   • JavaScript bundles (resources/js/)

4. CMS Integration Leverage Lara CMS components (e.g., @component('cms/page')):

   @component('lara-base-theme::components/page-header')
       <x-slot name="title">{{ $page->title }}</x-slot>
   @endcomponent
   

Integration Tips

• Blade Directives: Use @theme to check the active theme:

  @theme('base')
      <link rel="stylesheet" href="{{ asset('css/base-theme.css') }}">
  @endtheme
  

• Middleware: Bind theme-specific middleware in app/Http/Kernel.php:

  protected $middlewareGroups = [
      'web' => [
          \Appdezign\LaraBaseTheme\Http\Middleware\ThemeMiddleware::class,
      ],
  ];
  

• Service Providers: Extend functionality via the LaraBaseThemeServiceProvider:

  public function boot()
  {
      $this->loadViewsFrom(__DIR__.'/views', 'your-theme');
  }
  

Gotchas and Tips

Common Pitfalls

1. View Path Conflicts

   • Ensure custom theme views override base theme views correctly. Use php artisan view:clear if paths aren’t resolving.
   • Debug with:

     php artisan view:list
     

2. Asset Compilation Issues

   • The package assumes Laravel Mix/Vite is configured. If using Vite, ensure vite.config.js includes:

     resolve: {
         alias: {
             '@': path.resolve(__dirname, './resources/js'),
         },
     },
     

   • Clear cached assets:

     php artisan cache:clear
     npm run dev
     

3. Theme Activation

   • The active flag in config/cms.php must match the theme’s slug. Use:

     php artisan cms:theme:activate base
     

4. Dynamic Content Caching

   • Lara CMS caches dynamic content aggressively. Bypass with:

     @cache(false)
         {{ $dynamicContent }}
     @endcache
     

Debugging Tips

• Log Theme Events: Listen for theme events in EventServiceProvider:

  public function boot()
  {
      event(new \Appdezign\LaraBaseTheme\Events\ThemeActivated($theme));
  }
  

• Check Config: Validate config/lara-base-theme.php for overrides:

  'debug' => env('THEME_DEBUG', false), // Enable for verbose logs
  

• Blade Debugging: Use @dd() to inspect theme variables:

  @dd($this->theme)
  

Extension Points

1. Custom Directives Register new Blade directives in AppServiceProvider:

   Blade::directive('themeAsset', function ($path) {
       return "<?php echo asset(\"themes/{$path}\"); ?>";
   });
   

   Usage:

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

2. Theme Hooks Extend the theme system by publishing and overriding hook views:

   php artisan vendor:publish --tag="lara-base-theme-hooks"
   

   Example hook in resources/themes/your-theme/hooks/footer.blade.php:

   <div class="custom-footer">
       {{ $slot }}
   </div>
   

3. API Integration Use the theme’s API facade to fetch theme data:

   use Appdezign\LaraBaseTheme\Facades\Theme;
   
   $themeData = Theme::getActiveTheme();