Download the PHP package rareform/craft-inertia without Composer

Inertia.js Craft CMS Adapter

This is a server-side adapter for Inertia built with Craft CMS workflow simplicity in mind.

It utilizes Craft's routing, as well as Twig for crafting Inertia responses, rather than requiring they be written directly in PHP (as a traditional Inertia application does).

Ping CRM Demo — Ping CRM Repo

Requirements

This plugin requires Craft CMS 5.4.0 or later, and PHP 8.2 or later.

Installation

You can install this plugin from the Plugin Store or with Composer.

From the Plugin Store

Go to the Plugin Store in your project’s Control Panel and search for “Inertia”. Then press “Install”.

With Composer:

Open your terminal and run the following commands:

Be sure to follow the installation instructions for the client-side framework you use.

[!NOTE] Upon installing, the Inertia adapter will takeover all routing and expect all templates to respond with inertia protocol responses. To prevent this, you may set the takeoverRouting config option to false

[!IMPORTANT]

Required Reading

The Inertia documentation is a must-read to understand the protocol, the responsibilities of this adapter, and how to use Inertia on the client-side. The following sections will explain how to use this adapter, but assume you have a basic understanding of Inertia.

Defining Pages

Every page in your javascript application is backed by a Twig template which returns a page object. The page object defines which page component to render, and what prop data is received.

Note: templates are passed element variables (entry or category) automatically when the route is matched to either element type. If you want to pass the element as a prop automatically to your page component, set the injectElementAsProp configuration to true.

Shared Data

Shared data will automatically be passed as props to your application, sparing you the cumbersome tasks of redefining the same prop data in every page response. You can create multiple files for different shared prop responses.

Create a _shared directory at the root of your /templates directory, and use the inertiaShare variable:

This allows more flexibility for designating responses you may want to cache to reduce unnecessary repetitive queries.

Automatic Variable Capturing

You can enable automatic capturing of variables set with {% set %} in your twig files and have them passed as props to your Inertia components. This provides a cleaner, more intuitive way to pass data to your frontend without explicitly defining props.

Enable this feature in your config:

Prune Filter

With all variables being automatically captured and passed as props, you're inevitably going to have some large objects that you don't want to pass to your frontend. You can use the prune filter or function to remove properties from objects that are passed to your Inertia component.

Pull in Variables

Use the pull tag to include variables from a specified template and make them available in the current response twig file.

This is a simple DX alternative to using extends and block tags to share variables across templates. Note that the pull tag is only available in Inertia responses.

Saving Data

Craft CMS does not use traditional POST, PUT, PATCH, and DELETE requests for saving data, and instead uses the action parameter to when POSTing to various internal Craft controllers. This means saving data to Craft CMS data is a little different than what is expected in a traditional Inertia application.

Here's an example of how you could save an entry using Inertia's useForm helper without using the adapter's javascript helper:

Attaching the CSRF token, the action param, and the forceFormData option is required for Craft to process the request correctly, but it's recommended to use the adapter's helper to remove this repetitive boilerplate.

Using the Adapter's Helper

The adapter will automatically attach the CSRF token, action param, and set the forceFormData option to true for you, but needs access to the same Axios instance used by Inertia's native library.

For the majority of projects, all that's needed on your end is to attach Axios to the window object. The adapter will take care of the rest. (Having issues? Visit troubleshooting section below)

This looks much better. You can optionally reduce one extra step the helper takes by rendering the CSRF token info in your base template's head:

This extra step reduces additional fetch requests to Craft's sessions endpoint to get the CSRF token manually for unauthenticated users.

Configuration

Create an inertia.php file in your Craft /config directory. Shown are the default values:

Troubleshooting

Error HTTP 400 – Bad Request : Unable to verify your data submission

This error is usually caused by the CSRF token not being passed correctly with the form data.

If you manually stored the CSRF token in a meta tag in your base template, make sure you are using the correct name for the token. The default name is CRAFT_CSRF_TOKEN, but it can be changed in your Craft config.

If you attached Axios to the window object, make sure you are using the same instance of Axios that Inertia is using. If you have multiple versions of Axios installed (independently or through other packages) and are using Vite, you can resolve this by adding an alias to your Vite config:

Another way to resolve this is to use the resolutions field in your package.json file to force all packages to use the same version of Axios.