Lara Base Theme Laravel Package

Getting Started

Minimal Setup Steps

1. Install Lara CMS Core Ensure you have a Laravel 11+ project with Lara CMS installed (follow official docs).

   composer require appdezign/lara-cms
   

2. Publish the Base Theme Publish the base theme assets and configurations:

   php artisan vendor:publish --provider="Appdezign\LaraCms\Providers\ThemeServiceProvider" --tag="base-theme"
   

   This generates:

   • resources/views/vendor/lara-base-theme/ (Blade templates)
   • config/lara-cms.php (theme-related settings)

3. Register the Theme Add the base theme to your config/lara-cms.php under themes:

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

4. First Use Case: Render a CMS Page Create a route in routes/web.php:

   use Appdezign\LaraCms\Facades\Page;
   
   Route::get('/blog/{slug}', function ($slug) {
       $page = Page::findBySlug($slug);
       return view('vendor.lara-base-theme::pages.show', compact('page'));
   });
   

   Override the default template in resources/views/vendor/lara-base-theme/pages/show.blade.php.

Where to Look First

• Documentation: Start with Lara CMS Docs under the "Themes" section.
• Template Structure: Inspect vendor/appdezign/lara-base-theme/resources/views/ for Blade layouts and partials.
• Configuration: Check config/lara-cms.php for theme-specific settings (e.g., active_theme, default_layout).
• Service Providers: Review Appdezign\LaraCms\Providers\ThemeServiceProvider for registration logic.

First Practical Task

Customize the Layout:

1. Copy the default layout from vendor/appdezign/lara-base-theme/resources/views/layouts/app.blade.php to resources/views/vendor/lara-base-theme/layouts/app.blade.php.
2. Modify the copied file to include your project’s header, footer, or CSS/JS.
3. Test by visiting a CMS page (e.g., /home).

Implementation Patterns

Core Workflows

1. Template Overriding

• Pattern: Extend or replace Blade templates by copying files from the vendor directory to your project’s resources/views/vendor/lara-base-theme/ folder.
• Example: Override the default page template:

  cp vendor/appdezign/lara-base-theme/resources/views/pages/show.blade.php resources/views/vendor/lara-base-theme/pages/
  

  Customize the copied file (e.g., add a sidebar or modify the title tag).

2. Dynamic Content Rendering

• Pattern: Use Lara CMS’s Page facade to fetch and render content dynamically.
• Example:

  // In a controller or Blade view
  use Appdezign\LaraCms\Facades\Page;
  
  $page = Page::findBySlug('about-us');
  return view('vendor.lara-base-theme::pages.show', compact('page'));
  

• Blade Usage:

  @foreach($page->content as $block)
      @include('vendor.lara-base-theme::blocks.'.$block->type, ['block' => $block])
  @endforeach
  

3. Theme-Specific Assets

• Pattern: Publish and compile theme assets (CSS/JS) using Laravel Mix or Vite.
• Steps:
  1. Publish assets:

     php artisan vendor:publish --tag="base-theme-assets"
     

  2. Update webpack.mix.js to include theme-specific files:

     mix.copy('vendor/appdezign/lara-base-theme/resources/assets', 'public/vendor/lara-base-theme');
     

4. Extending Functionality

• Pattern: Use Laravel’s service providers to add custom logic.
• Example: Create a service provider to extend the theme:

  // app/Providers/ThemeExtensionsServiceProvider.php
  namespace App\Providers;
  
  use Illuminate\Support\ServiceProvider;
  
  class ThemeExtensionsServiceProvider extends ServiceProvider
  {
      public function register()
      {
          // Bind custom theme logic
          $this->app->singleton('custom.theme.helper', function () {
              return new \App\Services\CustomThemeHelper();
          });
      }
  }
  

  Register the provider in config/app.php.

5. Middleware for CMS Routes

• Pattern: Apply middleware to protect or modify CMS-specific routes.
• Example:

  // routes/web.php
  Route::middleware(['auth', 'cms.theme'])->group(function () {
      Route::get('/admin/theme', [ThemeController::class, 'dashboard']);
  });
  

Integration Tips

Laravel Ecosystem

• Authentication: Use Laravel’s built-in auth (e.g., auth()->check()) alongside CMS-specific checks.
• Validation: Reuse Laravel’s validation rules for CMS content (e.g., Validator::extend()).
• Events: Listen to Lara CMS events (e.g., PageCreated) via Laravel’s event system:

  Event::listen(PageCreated::class, function ($page) {
      // Custom logic after page creation
  });
  

Frontend Integration

• Tailwind/Alpine.js: Integrate modern frontend tools by extending the theme’s asset pipeline.

  // webpack.mix.js
  mix.postCss('resources/css/app.css', 'public/css', [
      require('tailwindcss'),
  ]);
  

• Inertia.js: For SPAs, use Inertia to render CMS content:

  return Inertia::render('Pages/Show', ['page' => $page]);
  

Database and Models

• Custom Models: Extend Lara CMS’s Eloquent models (e.g., App\Models\ExtendedPage) if additional fields are needed.

  class ExtendedPage extends \Appdezign\LaraCms\Models\Page
  {
      protected $casts = [
          'custom_field' => 'array',
      ];
  }
  

Multi-Environment Config

• Use Laravel’s .env to switch themes or configurations:

  THEME_ACTIVE=custom
  

  Access in Blade:

  @if(config('lara-cms.theme.active') === 'custom')
      {{-- Custom theme logic --}}
  @endif
  

Gotchas and Tips

Pitfalls

1. Vendor Directory Overrides

   • Issue: Forgetting to copy files from vendor/ to resources/views/vendor/ before modifying them, leading to lost changes on package updates.
   • Fix: Always copy files to your project directory first:

     cp -r vendor/appdezign/lara-base-theme/resources/views/* resources/views/vendor/lara-base-theme/
     

2. Lara CMS Dependency

   • Issue: Assuming the package works standalone without Lara CMS installed.
   • Fix: Verify all required Lara CMS models (e.g., Page, Media) exist in your database. Install Lara CMS core if missing:

     composer require appdezign/lara-cms
     php artisan lara-cms:install
     

3. Asset Pipeline Conflicts

   • Issue: CSS/JS conflicts when mixing theme assets with project-specific assets.
   • Fix: Use unique class names or namespaces for theme-specific styles:

     /* Theme-specific styles */
     .lara-base-theme-header { ... }
     

4. Caching Headaches

   • Issue: Blade templates or views not updating after changes due to Laravel’s cache.
   • Fix: Clear caches explicitly:

     php artisan view:clear
     php artisan cache:clear
     php artisan config:clear
     

5. Route Conflicts

   • Issue: Lara CMS routes clashing with existing Laravel routes.
   • Fix: Prefix CMS routes or use middleware to isolate them:

     Route::prefix('cms')->middleware(['web', 'cms'])->group(function () {
         // Lara CMS routes
     });
     

6. Database Schema Mismatches

   • Issue: The theme expects specific database tables (e.g., pages, media) that don’t exist.
   • Fix: Run Lara CMS migrations or create custom tables:

     php artisan migrate --path=vendor/appdezign/lara-cms/database/migrations
     

7. Laravel Version Mismatches

   • Issue: Using an incompatible Laravel version (e.g., Laravel 10 with a theme requiring Laravel 11).
   • Fix: Check the package’s composer.json for Laravel requirements and update your project accordingly.

Debugging Tips

1. Enable Debug Mode Set `APP_DEBUG=true