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.

Typed Schemas

php artisan flyo:types generates a class per block, navigation container and entity type of your integration into app/Flyo, so the IDE and PHPStan know the fields instead of a bare stdClass:

The command runs the flyo-generate-types generator of flyo/nitro-php against the authenticated https://api.flyo.cloud/nitro/v1/openapi/schemas endpoint, the public OpenAPI document has no typed schemas. The token is taken from config/flyo.php, so the FLYO_TOKEN of the .env file is used and the token is never passed as a command line argument. The classes go into the Flyo sub-namespace of the application namespace, App\Flyo for a standard Laravel project.

Annotate a block view with its generated class instead of \Flyo\Model\Block:

The classes are documentation only: nothing instantiates them, at runtime a block is still a \Flyo\Model\Block and its fields are still plain objects which can be empty, so keep guarding the field access. See the Typed Schemas section of the SDK for what the container and entity classes narrow.

Commit the generated files and run php artisan flyo:types --check in CI, with FLYO_TOKEN provided as a secret. To have the same entry point as the Next.js and Astro integrations (npm run flyo:types), add a composer script, anything after -- is appended to the command:

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.

Sitemap

The package registers /sitemap.xml, which lists every page and entity the api resolved a url for, each with a <lastmod> from the timestamp of its last content change. The locations are absolute urls built from the incoming request root.

The route is enabled by default. Turn it off with sitemap if the application should not serve that sitemap, for example because it renders a sitemap of its own at that path or none at all:

Page Middleware

The package registers a route for every page of the Flyo config. These routes are closures of the package, so an application adds behaviour to them through page_middleware: the listed middleware run on the CMS page routes only, after the web group and CachingHeaders, and before the page is loaded from the api. Hand written routes, like the entity detail pages, are not affected, so the middleware does not have to tell a CMS page apart from the rest of the application.

A middleware which returns early (a redirect, an abort()) saves the api request of the page. The Flyo\Model\ConfigResponse with the navigation containers is already in the container at that point. For example, a page with children but no content of its own can send the visitor to its first child:

Use a 302 for anything derived from the content, a permanent redirect stays in the browsers' cache after the editors changed the page tree.

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.

The cache headers are enabled by default. Turn them off with cache_headers if the responses should not be cached by the client or a cdn at all, the middleware then writes none of the three headers and a response keeps the Cache-Control header of the application, which is no-cache, private in Laravel unless something else writes one:

A response rendered from a draft link is still sent with its no store headers, see Draft Links.

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: