Getting Started

Minimal Setup

Installation

composer require thomaspark/bootswatch

Publish the package assets (if needed):

php artisan vendor:publish --provider="Thomaspark\Bootswatch\BootswatchServiceProvider" --tag=public

Basic Usage Include the Bootswatch CSS in your resources/views/layouts/app.blade.php:
```
<link href="{{ bootswatch('cerulean') }}" rel="stylesheet">
```
Or use the helper in a Blade template:
```
@bootswatch('cyborg')
```

First Use Case Quickly switch themes for a Laravel app without manual CSS overrides. Example:

// In a controller or service
$theme = request()->input('theme', 'cerulean');
view()->share('theme', $theme);

Then in Blade:

<link href="{{ bootswatch($theme) }}" rel="stylesheet">

Implementation Patterns

Dynamic Theme Switching

User Preference Storage Store the theme in session() or auth()->user()->theme:

$userTheme = auth()->user()->theme ?? 'cerulean';
view()->share('theme', $userTheme);

Middleware for Global Theming Create middleware to set the theme based on route, user, or request:

// app/Http/Middleware/SetTheme.php
public function handle($request, Closure $next) {
    $theme = $request->cookie('theme') ?? 'default';
    view()->share('theme', $theme);
    return $next($request);
}

Integration with Bootstrap

Bootstrap 5+ Compatibility Ensure your app.blade.php loads Bootstrap after Bootswatch:

<link href="{{ bootswatch($theme) }}" rel="stylesheet">
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">

Customizing Variables Override Bootswatch variables via SASS (if using Laravel Mix):

// resources/sass/app.scss
@import "~bootswatch/dist/scss/bootswatch";
@include bootswatch($theme);
$primary: #6c757d; // Override default

Theming in Livewire/Alpine

Dynamic Updates Use Alpine.js to toggle themes without page reload:

<div x-data="{ theme: '{{ $theme }}' }">
    <select x-model="theme" @change="window.location.href = `/theme/${theme}`">
        @foreach($themes as $theme)
            <option value="{{ $theme }}">{{ ucfirst($theme) }}</option>
        @endforeach
    </select>
</div>

Livewire Component

// app/Http/Livewire/ThemeSwitcher.php
public $theme = 'cerulean';
protected $listeners = ['themeUpdated' => 'updateTheme'];

public function updateTheme($theme) {
    $this->theme = $theme;
    session()->put('theme', $theme);
}

Gotchas and Tips

Common Pitfalls

Caching Issues
- Clear Laravel cache and view cache after theme changes:
```
php artisan cache:clear
php artisan view:clear
```
- Ensure config('view.compiled') is false in development.
Asset Paths
- If using vendor:publish, verify the published path in config/bootswatch.php:
```
'path' => public_path('vendor/bootswatch'),
```
- Default path: public/vendor/bootswatch.
Bootstrap Version Mismatch
- Bootswatch themes are version-specific. For Bootstrap 5, use:
```
<link href="{{ bootswatch('cerulean', '5') }}" rel="stylesheet">
```
- Defaults to Bootstrap 4 if no version specified.

Debugging Tips

Check Loaded Theme Inspect the <head> to confirm the correct theme CSS is loaded:
```
<link href="/vendor/bootswatch/cerulean.min.css" rel="stylesheet">
```
Verify Published Assets After publishing, check public/vendor/bootswatch/ for theme files.

Extension Points

Custom Themes Add your own theme by extending the package:

// app/Providers/BootswatchServiceProvider.php
public function register() {
    $this->app->singleton('bootswatch', function ($app) {
        $bootswatch = new \Thomaspark\Bootswatch\Bootswatch();
        $bootswatch->addTheme('mytheme', 'path/to/mytheme.css');
        return $bootswatch;
    });
}

Theme Configuration Override default themes in config/bootswatch.php:

'themes' => [
    'cerulean' => 'cerulean.min.css',
    'darkly'   => 'darkly.min.css',
    'mytheme'   => 'custom/mytheme.min.css', // Custom path
],

Dynamic Theme Loading Load themes conditionally (e.g., dark mode):

$theme = request()->userAgentContains('Dark') ? 'darkly' : 'cerulean';
view()->share('theme', $theme);

Bootswatch Laravel Package