Kirby Blade Laravel Package

Getting Started

• Install with Composer: composer require leitsch/kirby-blade. If your Kirby project doesn't use Composer for plugins, clone the repo into site/plugins/kirby-blade and run composer install inside it.
• Confirm registration: check the Panel's Plugins view or $kirby->plugins() for leitsch/kirby-blade. Kirby 4/5 auto-discovers plugins in site/plugins; Composer setups need the standard Kirby plugin wiring.
• Read the README first, then skim index.php and src/ to see how the Blade compiler and view finder are wired. That tells you the view search paths and the template suffix the package expects (typically .blade.php — verify the exact convention before mass-renaming).
• First use case: convert one template, not all of them. Create site/templates/home.blade.php alongside the existing home.php and render {{ $page->title() }}. Blade and PHP templates coexist, so migration can be incremental.

Implementation Patterns

• Layouts: use @extends/@section/@yield for site chrome. Keep layouts in a subfolder the view finder can reach (e.g. site/templates/layouts/) and confirm the dotted name resolves.
• Partials: @include('partials.nav', ['items' => $site->children()]). Prefer Blade includes over Kirby snippets for markup you render from templates; keep PHP snippets only for shared logic.
• Kirby data in scope: templates receive Kirby's standard vars — $page, $site, $kirby, $pages, $files, $user, $request. Treat them as already-passed view data; don't re-fetch what's in scope.
• Controllers: site/controllers/<template>.php returning an array is the closest analogue to a Laravel controller returning view data. Use it to keep logic out of Blade, then read the keys as normal variables in the template.
• Escaping: {{ }} escapes HTML. Kirby richtext and HTML fields need {!! $page->text()->kirbytext() !!} (or ->html()).
• Custom directives: wrap Kirby helpers once in the plugin bootstrap, e.g. Blade::directive('kirbytext', fn ($expr) => "<?php echo kirbytext($expr); ?>"), then use @kirbytext($page->text()) everywhere.
• Components: @component/@slot work well for cards, nav items, and other UI fragments repeated across templates.
• Migration flow: rename one template at a time, keep the .php original until the Blade version is verified, then delete. This keeps the site shippable throughout.

Gotchas and Tips

• Compiled view cache: Blade compiles to disk. Find the cache path (likely under site/cache/ or defined by the package) and know how to clear it — stale compiled templates are the usual cause of "my change isn't showing." Clear after every deploy and after editing directives.
• No Laravel framework: @if, @foreach, @include, @extends work; @csrf, @auth, route(), config(), and package-specific directives do not. Don't paste Laravel views assuming they'll run.
• Directive registration timing: register Blade::directive(...) in the plugin's boot/config path before views render. Registering late leaves the old compiled output in place until you clear the cache.
• Undefined variable errors: Blade only sees what Kirby passes. If a var is missing, pull it explicitly from $page, $site, or a controller rather than guessing at a Laravel-style global.
• Debugging: enable 'debug' => true in site/config/config.php, and when a directive misbehaves, open the compiled Blade file to see the generated PHP. Errors inside directives surface as opaque PHP errors, so the compiled output is usually faster to read than the stack trace.
• Pinning and support risk: 22 stars, zero dependents, and a fast-moving Kirby 5 target. Pin an exact version in composer.json, test Kirby upgrades in a branch, and watch the repo for breaking changes rather than assuming it tracks every Kirby minor.
• Extension points: custom directives, additional view paths/namespaces, and swapping the Blade compiler through the plugin's service registration (see src/) are the natural hooks. Never edit vendor/ — subclass or wrap in a project plugin so upgrades stay clean.