Download the PHP package flyo/nitro-laravel without Composer

Flyo Nitro Laravel Framework Module

Usage

Requires PHP 8.3 or newer and Laravel 11, 12 or 13.

publish the config

Adjust the token in config/flyo.php

Ensure to remove the default routes in routes/web.php which could conflict with the cms routes.

Views

Add/Adjust the cms.blade.php view file in resources/views, this is where the cms page loader starts:

Now all component block views are looked up in ressources/views/flyo, for example if you have a Flyo Nitro component block with name Text the view file would be ressources/views/flyo/Text.blade.php utilizing the following variables:

You can adjust the views namespace in the config file using views_namespace key.

To make the block editable you must place the Blade directive @editable($block) on the block's root HTML element. This ensures the Flyo editor can correctly detect the block and display the edit icon next to that element when the page is opened in the editor. In short: put @editable($block) on the outermost element of the block so clicking the icon opens this block for editing.

In raw php templates, or anywhere else the blade directive is not available (a controller, a string you build yourself), use Flyo\Laravel\Editable instead:

Editable::attr($block) returns the escaped data-flyo-uid="..." attribute, or an empty string when live edit is disabled. Editable::uid($block) gives you the raw uid, Editable::isEnabled() the live edit state. The marker alone is not enough though: the javascript which makes it interactive is loaded by the <x-flyo::head /> component, so your layout has to include it.

Live Edit

With live_edit enabled in config/flyo.php, the <x-flyo::head /> component loads the nitro js bridge from the CDN and wires everything the Flyo editor needs when the site is displayed inside the editor preview iframe:

• Page refresh: the editor can reload the preview after a change.
• Editor handshake: the preview announces itself, so the editor can show troubleshooting hints instead of a silent white screen when the preview is blocked or points at a build without live edit.
• Scroll to block: selecting a block in the editor scrolls the preview to it.
• Click to edit: hovering a block rendered with @editable($block) fades in a highlight ring plus a pencil button which opens that block in the editor.

The hover affordance appears after roughly half a second of hovering, so it does not flicker while the mouse crosses the page. It is drawn in a single overlay element outside of your markup: no styles, classes, attributes or listeners are added to your elements and layout and scrolling are untouched. On the live site nothing of it is loaded at all, since live_edit is disabled there.

The bridge url is pinned to the major version, so bridge releases are picked up automatically. To self host it or to pin an exact version, set the url in config/flyo.php:

Layout Variable

In order to build menus, the $config response from the api is a global available variable, for example this could be used in layout-components:

Make sure to include the <x-flyo::head> component in the head of your layout file, for example

This will add needed javascript for reloading and editin blocks in local environments and also assign all available meta informations.

The meta informations are taken from the api response of the current page (or entity when using the EntityController), which includes the title, description, image and the schema.org json-ld object rendered as an application/ld+json script.

A full layout example which could be placed in resources/views/layouts/app.blade.php:

Entity Detail

To display an entity detail page, you have to register a route, create a controller and a view file:

Routing File example

The Controller:

And the example tier.blade.php in the resources/views folder:

There is also a more generic controller available which can be used to display any entity detail page:

where the poi.blade.php file in the resources/views folder could look like this:

Search Engine Indexing

Pages and entities carry an is_indexable flag (flyo/nitro-php 3.2). When the api marks a document as not indexable, Head::metaPage() and Head::metaEntity() render a robots meta tag in the head:

This is not access control, the page or the entity still resolves like any other, it is only kept out of the search engines (and out of the sitemap and the search endpoint on the api side). A draft entity is always flagged as not indexable, see Draft Links.

The flag can also be set by hand, for a page which the application itself wants to hide:

Call it after metaPage() / metaEntity(), those assign the flag from the api response and would otherwise reset it.

Cache Headers

Flyo\Laravel\Middleware\CachingHeaders is applied to the CMS page routes and the sitemap. It writes one header for the browser and the two cdn specific ones which take precedence on the edge:

The stale-while-revalidate window is what keeps the origin quiet around an expiry: without it the moment an edge entry expires turns into an origin request for every visitor waiting on that url at that moment, with it the edge keeps answering from the stale copy and refreshes itself with a single background request. It is configured with server_cache_stale_while_revalidate_ttl, which defaults to 450 seconds (half of the default server_cache_ttl). Nothing has to be changed to get that behavior, set it to 0 to send max-age alone:

A visitor can therefore be served a page which is up to server_cache_ttl + server_cache_stale_while_revalidate_ttl seconds old, but only until the background refresh of the first request after the expiry has finished.

Set server_cache_ttl or client_cache_ttl to 0 to opt out of that layer, a server_cache_ttl of 0 sends no-store to the edge and never carries a stale window. Caching is switched off entirely when flyo.live_edit is enabled or APP_DEBUG is on, and a non successful response is not cached either. Flyo\Laravel\Middleware\CachingHeaders::cdnCacheControl($ttl, $staleTtl) builds the value of the cdn headers, in case an application writes them somewhere else too.

Add the middleware to a hand written route which serves CMS content and should be cached the same way:

Draft Links

A draft link is a shareable, expiring snapshot of an entity which is still offline in Flyo. It is requested through the regular entity endpoints, with a draft token in place of the slug or the unique id, and the api answers with is_draft set and a draft_expires_at timestamp:

Two things a route serving draft links has to respect:

1. The token does not look like a slug or a unique id, so a parameter pattern (->where(...)) has to let it through.
2. The entity type id does not apply to a token, so resolve without it:

A draft response is never cached

Once an entity was delivered through a draft link, the package makes the whole response uncacheable, for the client and for a cdn or another server side cache alike:

ETag and Last-Modified are dropped as well, and the server_cache_ttl / client_cache_ttl config is ignored for such a response. The draft snapshot is rewritten with every save of the editor and the link answers with a 404 once it expired, so a stored copy would keep serving content which is outdated or gone. The expiration timestamp is deliberately not used as a cache ttl.

The headers are written by Flyo\Laravel\Middleware\PreventDraftCaching, which the package registers as the outermost global middleware, so it also covers routes which do not use the CachingHeaders middleware.

Rendering a hint

EntityController hands the draft state to the view, so a template can tell the visitor that this is not the live page:

Everywhere else the state is readable from Flyo\Laravel\DraftMode:

A custom controller resolving an entity itself flags the draft by calling Flyo\Laravel\Components\Head::metaEntity($entity) (which every entity page does anyway to assign its meta data) or explicitly:

Multilanguage

The requests will pass the configured APP_LOCALE (which is used in laravel for localization) to the flyo api.

Defined the available locales in the config/flyo.php file:

The ServiceProvider will check for segments /de, /en in the url and set the locale in the request object if the locale is available in the config file.

Pass the language for entity Detail Requests:

Misc

In order to resolve the Configuration object somewhere in your application, you can use the following code:

Same for the page response

Example AGENTS.md

If you build your project with an AI coding assistant (Claude Code, Copilot, Cursor, etc.), drop an AGENTS.md file in your project root so the assistant understands your stack and knows where to find the Flyo/Nitro documentation. AGENTS.md is the vendor-neutral convention most coding agents read on startup, and if your tool uses a specific memory file such as CLAUDE.md, use that name too (or have it reference AGENTS.md).

Here is a minimal starting point you can copy and adapt. Note that it self-references this library's docs, the usage guide and the AI integration advisory, so the assistant can pull in the full Flyo Nitro setup and context on demand:

Documentation

Read More in the Docs

Upgrading

See UPGRADE.md for what changed between versions.

Package Development

1. Check the example-app/.env file to have a correct flyo token.
2. Go to example-app and run php artisan serve to get the example app running.

Run the checks the CI runs: