Laravel Folio is a powerful, page-based router specifically designed to simplify routing in Laravel applications. As a package available for Laravel, Folio aims to make generating a route as effortless as creating a Blade template file

1 Core Concepts and Installation

Folio operates on the principle that the file path of a Blade template determines its URI

1.1. Installation and Setup

To begin using Folio, you must install the package using Composer. 

composer require laravel/folio

Following installation, executing the folio:install Artisan command is necessary, which installs Folio's service provider and registers the directory it will scan for routes

php artisan folio:install

1.2. Page Paths and Directories

By default, Folio serves pages created within your application's resources/views/pages directory. For instance, placing a greeting.blade.php file in this default directory makes the page accessible via the /greeting URL.

Developers can customize or register multiple Folio paths by invoking the Folio::path method, typically within the Folio service provider's boot method. This is useful for separating areas like an "admin" section from "guest" pages. The Folio::uri method specifies the "base URI" for a registered path (e.g., associating /admin with resources/views/pages/admin)

use Laravel\Folio\Folio;

Folio::path(resource_path('views/pages/guest'))->uri('/');

Folio::path(resource_path('views/pages/admin'))
    ->uri('/admin')
    ->middleware([
        '*' => [
            'auth',
            'verified',

            // ...
        ],
    ]);

1.3. Route Structure

Folio provides flexible ways to structure and access pages:

1.3.1. Creating Routes

A route is created simply by placing a Blade template in a Folio mounted directory (defaulting to resources/views/pages). A file like pages/schedule.blade.php is accessible at http://example.com/schedule. The list of registered Folio routes can be viewed using the php artisan folio:list command

php artisan folio:list

1.3.2. Nested Routes

Nested routes are created by structuring pages within directories (e.g., pages/user/profile.blade.php corresponds to the URI /user/profile)

php artisan folio:page user/profile

# pages/user/profile.blade.php → /user/profile

1.3.3 Index Routes

Placing an index.blade.php file within a directory makes that page the "index" or root for that directory (e.g., pages/users/index.blade.php serves requests to /users)

php artisan folio:page index
# pages/index.blade.php → /

php artisan folio:page users/index
# pages/users/index.blade.php → /users

2 Advanced Routing Features

2.1 Route Parameters

Segments of the URL can be injected as variables into the Blade template by encapsulating the segment name in square brackets in the filename

• A page named pages/users/[id].blade.php will handle requests like /users/1, injecting the ID value as the variable $id into the template
• To capture multiple trailing segments of a URI, the segment name can be prefixed with three dots (e.g., users/[...ids].blade.php), and the captured segments will be injected as an array (e.g., $ids)

2.2 Route Model Binding

Folio leverages Laravel's route model binding for segments that correspond to an application's Eloquent models

• A page named users/[User].blade.php will automatically attempt to resolve the corresponding User model instance based on the URI segment
• The resolved model is injected into the Blade template, with the variable name converted to camel case (e.g., $user)
• The key used for resolving the model defaults to id, but this can be customized in the filename (e.g., [Post:slug].blade.php uses the slug column)
• To retrieve soft deleted models, the withTrashed function must be invoked within the page's template

2.3. Subdomain Routing

Folio supports routing pages based on the incoming request's subdomain using the domain method when registering a path. The domain method also allows capturing parts of the domain as parameters, which are then injected into the page template

use Laravel\Folio\Folio;

Folio::domain('admin.example.com')
    ->path(resource_path('views/pages/admin'));

3 Customization and Control

3.1 Middleware

Middleware can be applied to Folio routes in two ways:

3.1.1 Group Middleware

Middleware can be applied to a group of pages by chaining the middleware method after Folio::path registration. The middleware array can be keyed by URL patterns using the * character as a wildcard (e.g., 'admin/*' applies middleware only to routes starting with admin/). Inline, anonymous middleware can also be included via closures

use Laravel\Folio\Folio;

Folio::path(resource_path('views/pages'))->middleware([
    'admin/*' => [
        'auth',
        'verified',

        // ...
    ],
]);

3.1.2. Page Middleware

Middleware can be applied to an individual page by invoking the middleware function within that page's template (e.g., middleware(['auth', 'verified']))

<?php

use function Laravel\Folio\{middleware};

middleware(['auth', 'verified']);

?>

<div>
    Dashboard
</div>

4 Render Hooks

By default, Folio returns the Blade template content. However, the response can be customized using the render function within the page's template. The closure passed to render receives the View instance, route parameters, and model bindings, allowing the developer to add additional data to the view or return a completely custom response (e.g., an "Unauthorized" response with status code 403)

<?php

use App\Models\Post;
use Illuminate\Support\Facades\Auth;
use Illuminate\View\View;

use function Laravel\Folio\render;

render(function (View $view, Post $post) {
    if (! Auth::user()->can('view', $post)) {
        return response('Unauthorized', 403);
    }

    return $view->with('photos', $post->author->photos);
}); ?>

<div>
    {{ $post->content }}
</div>

<div>
    This author has also taken {{ count($photos) }} photos.
</div>

4.1. Named Routes

Routes can be assigned names by invoking the name function within the page's template.

<?php

use function Laravel\Folio\name;

name('users.index');

 This allows URLs to be generated using Laravel's standard route function

<a href="{{ route('users.index') }}">
    All Users
</a>

4.2. Route Caching

For optimal performance, Laravel Folio is designed to utilize Laravel's route caching capabilities. Folio listens for the route:cache Artisan command to ensure that page definitions and route names are properly cached

5 References Link

• https://laravel.com/docs/12.x/folio
• https://github.com/laravel/folio
• https://laravel-news.com/laravel-folio