Getting Started

Minimal Setup

Installation Add the package via Composer in your Laravel project:

composer require cvepdb-cms/module-themes

Publish the package configuration (if available):

php artisan vendor:publish --provider="Cvepdb\Themes\ThemesServiceProvider"

Service Provider & Routes Ensure the package’s service provider is registered in config/app.php under providers. Check for theme-related routes in routes/web.php (if the package includes them).
First Use Case: Activating a Theme
- Locate the themes directory in your project (default: resources/themes or storage/app/themes).
- Create a new theme folder (e.g., my-theme) with required files (index.blade.php, assets/).
- Activate it via the admin panel (if provided) or manually in the database (check themes table or config).
Configuration Review config/themes.php (if published) for:
- Default theme settings.
- Theme storage paths.
- Cache settings (e.g., cache_themes: true).

Implementation Patterns

1. Theme Structure & Organization

Standardized Directory Layout Themes should follow a consistent structure (e.g., views/, assets/css/, assets/js/). Example:

/resources/themes/my-theme/
├── index.blade.php       # Main template
├── layouts/app.blade.php # Shared layout
├── assets/
│   ├── css/style.css
│   └── js/script.js
└── config.php            # Theme-specific config (optional)

Blade Templates Use @include and @extends for modularity. Example:

@extends('themes.my-theme.layouts.app')
@section('content')
    <h1>Welcome to My Theme</h1>
@endsection

2. Dynamic Theme Switching

Middleware for Theme Detection Use middleware to detect and apply themes based on:

User role (e.g., admin vs. user).
URL parameters (e.g., /theme/{name}).
Database settings. Example middleware:

namespace App\Http\Middleware;
use Cvepdb\Themes\Facades\Theme;
class SetTheme
{
    public function handle($request, Closure $next) {
        $theme = Theme::getActiveTheme(); // Assume facade exists
        view()->share('theme', $theme);
        return $next($request);
    }
}

Theme Facade/Helper Leverage the package’s facade (if available) to:
- List available themes:
```
$themes = Theme::listThemes();
```
- Activate a theme:
```
Theme::setActiveTheme('my-theme');
```
- Check if a theme is active:
```
if (Theme::isActive('my-theme')) { ... }
```

3. Asset Management

Versioned Assets Use Laravel Mix/Vite to compile theme assets with unique hashes:
```
// resources/themes/my-theme/assets/js/app.js
require('./theme.js');
```
Compile with:
```
npm run dev
```
Output will be hashed (e.g., css/style.css?id=1234).

Theme-Specific Asset Loading Dynamically load assets in Blade:

<link href="{{ asset("themes/{$theme}/assets/css/style.css") }}" rel="stylesheet">

4. Theme Configuration

Override Defaults Publish and modify config/themes.php to:
- Change default theme: 'default' => 'my-theme'.
- Adjust cache behavior: 'cache_themes' => false.
- Set theme paths: 'theme_paths' => [resource_path('themes'), storage_path('app/themes')].
Theme-Specific Config Store theme-specific settings in config.php within the theme directory and load them via:
```
$themeConfig = require(resource_path("themes/{$theme}/config.php"));
```

5. Integration with Views

Service Provider Binding Bind the theme resolver in AppServiceProvider:

public function boot() {
    view()->composer('*', function ($view) {
        $view->with('activeTheme', Theme::getActiveTheme());
    });
}

Dynamic View Resolution Override Laravel’s view resolver to prioritize themes:

// app/Providers/ViewServiceProvider
public function boot() {
    $this->app['view']->addNamespace('themes', resource_path('themes'));
}

Then use:

@include('themes.' . $activeTheme . '.index')

6. Admin Panel Integration

Theme Management UI If the package includes an admin panel:
- Use the provided routes (/admin/themes) to:
  - List/install themes.
  - Activate/deactivate themes.
  - Preview themes.
- Extend the UI via service provider hooks (if available).

Custom Admin Routes Add routes for theme management:

Route::prefix('admin/themes')->group(function () {
    Route::get('/', [ThemeController::class, 'index']);
    Route::post('/activate', [ThemeController::class, 'activate']);
});

Gotchas and Tips

Pitfalls

Missing Theme Directories
- Issue: The package expects themes in resources/themes or storage/app/themes, but they’re missing.
- Fix: Create the directory and ensure proper permissions:
```
mkdir -p resources/themes
chmod -R 755 resources/themes
```
Caching Conflicts
- Issue: Theme changes aren’t reflected due to Blade caching.
- Fix: Clear views and config:
```
php artisan view:clear
php artisan config:clear
```
- Disable caching in config/themes.php temporarily for debugging:
```
'cache_themes' => false,
```
Asset Path Errors
- Issue: Assets (CSS/JS) fail to load with 404 errors.
- Fix:
  - Verify asset paths in Blade use asset() or mix():
```
<link href="{{ mix("themes/{$theme}/assets/css/style.css") }}" rel="stylesheet">
```
  - Ensure public_path() is correctly configured in config/filesystems.php.
Namespace Collisions
- Issue: Theme Blade files conflict with app views (e.g., resources/views/home.blade.php vs. resources/themes/my-theme/home.blade.php).
- Fix: Use explicit namespace resolution:
```
@include('themes.' . $activeTheme . '.home')
```
Database Dependencies
- Issue: The package relies on a themes table, but migrations aren’t run.
- Fix: Check for migrations in database/migrations/ and run:
```
php artisan migrate
```
Middleware Order
- Issue: Theme middleware isn’t applied because of registration order.
- Fix: Ensure SetTheme middleware is registered before other middleware in app/Http/Kernel.php:
```
protected $middleware = [
    \App\Http\Middleware\SetTheme::class,
    // Other middleware...
];
```

Debugging Tips

Log Active Theme Add a debug line in middleware:

\Log::debug('Active theme:', ['theme' => $theme]);

Check logs with:

tail -f storage/logs/laravel.log

Verify Theme Paths Dump theme paths in a route:

Route::get('/debug-themes', function () {
    dd(config('themes.theme_paths'));
});

Test with a Minimal Theme Create a barebones theme to isolate issues:

/resources/themes/test-theme/
└── index.blade.php

@extends('layouts.app')
@section('content') <h1>Test Theme</h1> @endsection

Extension Points

Custom Theme Resolver Extend the theme resolution logic by binding a custom resolver:

// app/Providers/AppServiceProvider
public function register() {
    $this->app->bind(\Cvepdb\Themes\Contracts\ThemeResolver::class, function () {
        return new \App\Services\CustomThemeResolver();
    });
}

Theme Events Listen for theme-related events (if the package supports them):

// app/Providers/EventServiceProvider
protected $listen = [
    \Cvepdb\Themes\Events\ThemeActivated::

Module Themes Laravel Package