🪄 Work in progress
This documentation is still a work in progress, so please don’t mind the mess. We also want to assure you that any corpses you see are used for completely legal and sanctioned necromantic purposes. Absolutely no funny business is taking place here.
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.
You can use the
php artisan make:wizard command to have
conjure generate a new wizard skeleton for you. Check the section on commands for more information.
Before our wizard can do anything, it needs to be registered so
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,
falls back to the defaults defined in the
AbstractWizard base class. This why currently all routes are called
Filling in the details
Our wizard is still pretty bare bones, so let's start filling in some of the details.
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.
NoteArcanist doesn’t actually display the
titleanywhere. Instead, it will be passed to each view as part of the
wizardkey. Check the section on view data for more information about this.
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
If we look at our application routes again, we can see that they now sound much cooler:
Ah, much better.
Configuring the route prefix
wizard prefix for all routes. This can be configured via the
route_prefix option in the
arcanist.php config file. Check out the configuration page for reference.
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
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:
- Provide their email and password
- Select a subscription plan
- Upload a user avatar
Does that mean users are forced to upload an avatar? Maybe! It depends on the configuration of the
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
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.
More on actions
Check out the page on actions for more information on how actions work.
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
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,
will fall back to using the route defined in the
redirect_url key in the
arcanist.php config file.
Check out the configuration section of the documentation for a complete list of all available configuration options.
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.
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.