Getting Started / Conventions

Docs Getting Started

Conventions

The conventions described below are NOT mandatory. Feel free to pick what you like and also come up with your own conventions. With that out of the way, here's a list of conventions you may find helpful.

Resource Routes

Laravel supports resource routes, which play really well with Hotwire for most things. They create route names such as posts.index, posts.store, etc.

If you don't want to use resource routes, at least consider following the naming convention: render forms in routes whose names end in .create, .edit, or .delete, and name their handler routes with .store, .update, or .destroy, accordingly.

Turbo Laravel uses this naming convention so that, instead of redirecting after failed validations, it triggers an internal request to the application to re-render the form and returns it with a 422 status code. The form should re-render with the old() input values and any validation messages.

You may want to define exceptions to the route guessing behavior. If that's the case, set them in the redirect_guessing_exceptions key of the config/turbo-laravel.php config file:

php
return [
    // ...
    'redirect_guessing_exceptions' => [
        '/some-page',
    ],
];

When using this config, the regular redirect behavior will still happen for those routes, but the package will not attempt to guess which routes render their forms. See the Validation Response Redirects page to know more about why this happens.

Partials

You may want to split up your views into smaller chunks (aka. "partials"), such as a comments/_comment.blade.php to display a comment resource, or comments/_form.blade.php to display the form for both creating and updating comments. This allows you to reuse these partials in Turbo Streams.

Alternatively, you may switch your partials' location to a {plural}.partials.{singular} convention by calling the Turbo::usePartialsSubfolderPattern() method of the Turbo Facade from your AppServiceProvider::boot() method:

php
<?php

namespace App\Providers;

use HotwiredLaravel\TurboLaravel\Facades\Turbo;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Turbo::usePartialsSubfolderPattern();
    }
}

You may also want to define your own pattern for partials, which you can do using the Turbo::resolvePartialsPathUsing() method. This method accepts either a string pattern or a Closure. If you pass a string pattern, you'll have two placeholders available: {singular} and {plural}, which will get replaced with the model's singular and plural names, respectively, when the pattern is used. If you pass a Closure, you'll have the model instance available and you must return the view pattern using Laravel's dot notation convention. The placeholders will also be applied to the pattern returned from the Closure, if you need that. Here's how you could manually define the partials subfolder pattern:

php
<?php

namespace App\Providers;

use HotwiredLaravel\TurboLaravel\Facades\Turbo;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Turbo::resolvePartialsPathUsing('{plural}.partials.{singular}');

        // Or...

        Turbo::resolvePartialsPathUsing(fn ($model) => 'partials.{singular}');
    }
}

For reference, the default pattern is {plural}._{singular}, while the subfolder pattern is {plural}.partials.{singular}. For a Comment model, these resolve to the comments._comment and comments.partials.comment views, respectively.

The models' partials (such as a comments/_comment.blade.php for a Comment model) should only rely on having a single $comment variable passed to them. That's because Turbo Stream Model Broadcasts (an optional feature, by the way) rely on these conventions to figure out the partial for a given model when broadcasting, and will pass the model to that partial using the class basename in camelCase as the variable name. Again, this is optional, you can customize most of these things or create your own model broadcasting convention. Read the Broadcasting section to learn more.

Turbo Stream Channel Names

Note: Turbo Stream Broadcasts are optional.

You may use the model's Fully Qualified Class Name (aka. FQCN) with a wildcard as your Broadcasting Channel authorization routes, such as App.Models.Comment.{comment} for a Comment model living in App\Models\. The wildcard's name doesn't matter, as long as there is one. This is the default broadcasting channel naming convention in Laravel.