Layouts Ui Laravel Package

Getting Started

netgen/layouts-ui is the admin-facing UI bundle for Netgen Layouts — a Symfony bundle, not a Laravel package. Before composer require netgen/layouts-ui you need the full stack in place:

composer require netgen/layouts-core netgen/layouts-standard netgen/layouts-ui

For a Laravel app, the realistic path is not to install this into your vendor/ tree and wire a service provider (there isn't one, and the bundle is hard-coupled to the Symfony DI container, HttpKernel, and asset pipeline). Instead:

1. Stand up a small Symfony app (or a sidecar container) that runs Layouts + Layouts UI.
2. Treat that app as the layout/render authority.
3. Consume its rendered output or admin iframe from Laravel.

Where to look first in the repo:

• src/Netgen/Layouts/UI/ (or lib/) — the bundle class, controllers, and route definitions. This is what exposes /layouts, /layouts/{id}/edit, /layouts/block/{id} etc.
• Resources/ui/ — the compiled React/Redux admin app. If you see a manifest.json or hashed bundles, that's your static asset surface.
• Resources/config/ — routing and service definition; skim it to understand which URLs the UI expects and which core services it pulls.

First concrete use case: render a "page" whose body is a saved layout. In Laravel you'd hit the Symfony app's API/route with the layout ID or the resolution context, receive HTML, and echo it into your Blade view. Do not try to instantiate LayoutResolver from Laravel — you'll be fighting autoloading and container wiring within an hour.

Implementation Patterns

Admin-in-iframe. The most common integration is to mount the Symfony-served UI (usually under /admin/layouts) in an iframe inside your Laravel admin panel. Authenticate via a shared JWT or session bridge; the UI reads/writes through Symfony routes only. This is the only pattern that gives you the editor "for free."

Headless render endpoint. Add a small controller in the Symfony app that accepts a layout ID + context array and returns rendered HTML ($layout->render() style). From Laravel:

$html = Http::withToken(config('layouts.token'))
    ->post(config('layouts.endpoint') . '/render', [
        'layout_id' => $page->layout_id,
        'context'   => ['route' => $request->path()],
    ])->body();

Cache that per (layout_id, context_hash) in Redis — the renderer is not cheap.

Layout resolution via context. Netgen Layouts resolves layouts through rules and targets (path, section, content type). Configure these in the Symfony side; keep Laravel purely as a consumer that passes route_name, path, and any content type identifier. Resist the urge to reimplement resolution in Eloquent — you'll diverge from the UI's expectations immediately.

Block data as JSON. Custom block definitions live in Symfony as PHP classes with value types; their serialized payload is JSON stored by core. If you need Laravel to know about block content (e.g., to index it), read the JSON out of the layout's block table and hydrate a DTO — don't try to map it to Eloquent models.

Asset publishing. The UI ships pre-compiled assets in Resources/ui. In Symfony you'd run assets:install + webpack_encore:build (or publish the bundle assets). Serve them from the Symfony host; don't try to php artisan vendor:publish these — they carry Symfony paths and manifest references.

Local development loop. Use Docker Compose with two services: app (Laravel) and layouts (Symfony). Point Laravel's LAYOUTS_ENDPOINT at the sidecar. This keeps the Symfony dev workflow (bin/console cache:clear, yarn watch) isolated from your Laravel artisan serve loop.

Gotchas and Tips

• No Laravel service provider exists, and none is coming. The composer.json for this package declares Symfony bundle metadata; php artisan package:discover will ignore it. Any attempt to auto-register it in a Laravel app results in "class not found" errors on the Symfony Kernel.
• ext-intl and ext-json are hard requirements. The UI does translation lookups and JSON round-trips constantly. Missing intl triggers fatal errors deep inside a translation service, not a friendly message.
• Version pinning is brutal. Layouts UI tracks Layouts core versions 1:1 (e.g., layouts-ui ^1.4 requires layouts-core ^1.4 and specific symfony/* versions). Mixing minors produces blank admin pages with console errors, not PHP exceptions.
• Clear the Symfony cache after any UI change. bin/console cache:clear — otherwise the asset manifest points at stale hashed filenames and you get 404s for app.[hash].js in the browser console while Symfony's own logs show nothing.
• Routes are hard-coded under /_layouts (or a configurable prefix) and expect an authenticated firewall context. Without a working Symfony security.firewall, the UI throws 403s on /layouts/api/* rather than redirecting. Check security.yaml, not just routing.
• Debugging blank screens: open the browser devtools Network tab before the console. Nine times out of ten it's a missing compiled asset or a 401 to the API, not a JS bug. The React app fails silently on unhandled promise rejections.
• Extension points to know about: custom block definitions (BlockDefinitionInterface), value types (for typed block content), layout resolvers (custom resolution logic), and targets. All of these are PHP classes registered via Symfony DI tags — you cannot add them from Laravel.
• Don't fork the React app unless you're prepared to maintain it. It's a non-trivial Redux codebase (several hundred components) with tight coupling to the API contract. Customization should happen via block definition config schemas, not by editing the frontend.
• If your Laravel app doesn't already use Symfony elsewhere, seriously evaluate whether you need this package at all. A Laravel-native alternative (Wink, custom Blade layout system, or Filament form-based page builders) will cost you days less than a sidecar deployment. netgen/layouts-ui is a good editor attached to a heavy stack — it earns its weight only when you're already committing to Netgen Layouts.