Wizards

The Wizard is the top-level component of your form. It takes care of navigating between steps, handling form submissions and providing shared data that should be available to all steps.

Creating new wizards

All wizards extend from Arcanist\AbstractWizard. This base class provides almost all the functionality you need out of the box.

Registering wizards

Before our wizard can do anything, it needs to be registered so Arcanist knows about it. We can do so by adding it to the wizards array in our arcanist.php config file.

If we check our application routes now using php artisan route:list, we would indeed see a bunch of new routes that were registered. Here are the routes you should see:

Since we haven’t really configured our wizard yet, Arcanist falls back to the defaults defined in the AbstractWizard base class. This why currently all routes are called new-wizard.

Filling in the details

Our wizard is still pretty bare bones, so let's start filling in some of the details.

Naming wizards

Every good wizard needs a name. To give your wizard a name, you can overwrite the static $title property that comes with the base class.

If you need more control, for example because you want to localize your wizard’s title, you can override the title() method instead.

Slugs

Now that our wizard is no longer nameless, let's configure the slug next. The slug is used to generate both the names as well as the actual URLs for all routes of this wizard.

When we looked at the routes that were registered above, we saw that they all contained new-wizard. This is because that’s the default slug provided by the AbstractWizard base class.

To make your wizard cool and unique, you can (and should) overwrite the static $slug property.

If we look at our application routes again, we can see that they now sound much cooler:

Ah, much better.

Adding steps

Our wizard now has a name and slick URLs, but it’s not actually doing anything yet. To change that, we specify the list of steps that make up this wizard in the steps property.

For more information on how exactly steps work, check the next section of the docs.

Note that the order of the steps is important. The way we’ve set up our wizard now, the user needs to:

1. Provide their email and password
2. Select a subscription plan
3. Upload a user avatar

After a step was submitted, Arcanist will automatically redirect to the next step in the wizard. If the submitted step happens to be the last one in the wizard, Arcanist will then call the wizard’s configured action.

“What action?” you might say. I’m glad you asked.

Configuring the action

True to their literary counterparts, wizards in Arcanist don’t actually do anything themselves. They instead delegate the actual work to a separate Action class once the last step of the wizard was submitted. Which class gets called is configured via the onCompleteAction property of the wizard.

Passing data to actions

By default, the action gets passed an array containing all data that has been collected by the wizard’s steps. This data can be accessed using the $this->data(?string $key, mixed $default = null) method of the wizard.

Sometimes you might want to transform the data before it gets passed to the action, however. You might want to transform the data array into a data transfer object (DTO), for example. You can do this by overwriting the transformWizardData() method.

Redirecting after completing the wizard

After the action was run successfully, Arcanist will redirect the user to a different page. The target of the redirect can be configured in multiple ways, both globally, as well as on a per-wizard basis.

Default redirect target

If no explicit redirect target is defined in the wizard, Arcanist will fall back to using the route defined in the redirect_url key in the arcanist.php config file.

Wizard-specific redirects

You probably want to redirect the user to a specific page based on the wizard most of the time. You can configure this in one of the following ways.

For simple cases, you can implement the redirectTo method of the wizard and return the intended target URL.

If you need full control over the redirect response, you can use the onAfterComplete method instead. This method is passed an ActionResult instance—which contains the result of calling the wizard’s action—and needs to return a RedirectResponse. This allows you to redirect to the detail page of a model that was created inside the action, for example.

Configuring middleware

If you want to apply a specific set of middleware to a particular wizard, you can implement the static middleware method in your wizard class.

This middleware gets merged with the global wizard middleware defined in the configuration.