Getting Started

Minimal Setup

Installation

composer require capell-app/frontend

Publish the package assets and config:

php artisan vendor:publish --provider="CapellApp\Frontend\FrontendServiceProvider" --tag="config"
php artisan vendor:publish --provider="CapellApp\Frontend\FrontendServiceProvider" --tag="views"

Basic Route Definition Define a public route in routes/web.php:

use CapellApp\Frontend\Facades\Frontend;

Route::get('/blog', function () {
    return Frontend::render('blog.index', [
        'posts' => Post::latest()->get(),
    ]);
});

First Render Create a Blade template at resources/views/blog/index.blade.php:

@extends('frontend::layouts.app')
@section('content')
    @foreach($posts as $post)
        <h2>{{ $post->title }}</h2>
    @endforeach
@endsection

Verify Caching Check if the response includes X-Cache: HIT after subsequent requests.

Implementation Patterns

Routing and Boundaries

Public Route Grouping Use the frontend middleware group for all public routes:

Route::middleware(['frontend'])->group(function () {
    Route::get('/{path}', [FrontendController::class, 'handle']);
});

Dynamic Theme Switching Override the active theme in a middleware:

public function handle($request, Closure $next) {
    if ($request->has('theme')) {
        config(['frontend.theme' => $request->theme]);
    }
    return $next($request);
}

Caching Strategies Leverage Frontend::cache() for manual cache control:
```
return Frontend::cache(3600)->render('home.index', $data);
```

Integration with CMS

Content Fetching Use Frontend::content() to fetch Capell CMS data:

$page = Frontend::content('pages/home');
return Frontend::render('home', $page->toArray());

Asset Management Publish and version assets via:

Frontend::asset('css/app.css'); // Returns full URL with version hash

Blade Directives

Common Directives

@frontendCache(3600) <!-- Cache block for 1 hour -->
@frontendTheme('dark') <!-- Switch theme for block -->
@frontendAsset('js/app.js') <!-- Auto-versioned asset -->

Gotchas and Tips

Pitfalls

Cache Invalidation Clear the frontend cache after CMS content updates:
```
php artisan frontend:clear-cache
```
Or programmatically:
```
Frontend::clearCache();
```
Theme Conflicts Ensure theme files are named correctly (e.g., resources/themes/{theme}/views/partials/header.blade.php). Use Frontend::theme() to debug the active theme:
```
dd(Frontend::theme());
```
Route Overrides Avoid naming conflicts with Capell’s built-in routes. Prefix custom routes:
```
Route::get('/custom/{path}', [CustomController::class])->name('frontend.custom.');
```

Debugging

Enable Debug Mode Set FRONTEND_DEBUG=true in .env to log cache misses and theme switches.
View Debugging Use @frontendDebug in Blade to inspect rendered data:
```
@frontendDebug($posts)
```

Extension Points

Custom Cache Drivers Extend CapellApp\Frontend\Contracts\CacheDriver for Redis/Memcached:

class RedisCacheDriver implements CacheDriver {
    // Implement cache logic
}

Bind it in config/frontend.php:

'cache' => \App\Services\RedisCacheDriver::class,

Middleware Hooks Add hooks in app/Providers/FrontendServiceProvider.php:

public function boot() {
    Frontend::hook('beforeRender', function ($view, $data) {
        // Modify data before rendering
    });
}

Asset Pipeline Override asset paths in config/frontend.php:

'assets' => [
    'base_url' => 'https://cdn.example.com',
    'version' => 'v2',
],

Frontend Laravel Package