laravel-setup-wizard

by marvinlabs

A Laravel package to help you build a web setup wizard for your application

203 Stars 22 Forks Last release: over 3 years ago (0.2.1) MIT License 21 Commits 4 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Laravel Setup Wizard

A Laravel package to help you build a web setup wizard for your application

Setup

Add the package to your project

composer require marvinlabs/laravel-setup-wizard

Declare the service provider and the alias

Add the following line to your

config/app.php
file:
'providers' => [
    // ...
    // Other Service Providers
    // ...
    MarvinLabs\SetupWizard\ServiceProvider::class,
],

'aliases' => [ // ... // Other aliases // ... 'SetupWizard' => MarvinLabs\SetupWizard\Facades\SetupWizard::class, ],

Declare the required middleware

Add the following line to your

app/Http/Kernel.php
file:
protected $middlewareGroups = [
    // ...
    // Other Middleware
    // ...

'setup_wizard' => [
    \Illuminate\Session\Middleware\StartSession::class,
    \Illuminate\View\Middleware\ShareErrorsFromSession::class,
    'setup_wizard.initializer',
]

];

protected $routeMiddleware = [ // ... // Other Middleware // ...

'setup_wizard.initializer' => \MarvinLabs\SetupWizard\Middleware\SetupWizardInitializer::class,
'setup_wizard.trigger'     => \MarvinLabs\SetupWizard\Middleware\SetupWizardTrigger::class,

];

Enable the middleware to launch the wizard if necessary

If you want to launch the setup wizard automatically when required, you need to add the

SetupWizardTrigger
middleware to the routes you wish to protect. For instance, if you have a route group to show an administration panel, you could do it there:
Route::group([
    'prefix'     => 'admin', 
    'middleware' => 'setup_wizard.trigger'
], function () {
        // ...
});

This way, the setup wizard will only be triggered when trying to access the administration panel.

The middleware to trigger the setup wizard should be put as the first one of the middleware list

Publish assets

To get the CSS right, you need to at least publish the package assets to your public directory:

php artisan vendor:publish --provider="MarvinLabs\SetupWizard\ServiceProvider" --tag="assets"

Optionally, you can publish more files from the package in order to be able to override them. Use the artisan command like you would for any other package (will publish files from all vendor packages):

php artisan vendor:publish

Or you can publish only some of the package files to override just what you need. The library has tagged them into 4 different categories (assets category has been published before):

php artisan vendor:publish --provider="MarvinLabs\SetupWizard\ServiceProvider" --tag="config"
php artisan vendor:publish --provider="MarvinLabs\SetupWizard\ServiceProvider" --tag="views"
php artisan vendor:publish --provider="MarvinLabs\SetupWizard\ServiceProvider" --tag="translations"

If you had published some files before and want to overwrite them, use the

--force
flag with the artisan commands above.

Configuration

The configuration of the package is done via the

config/setup_wizard.php
file. Each configuration option is documented within that file and hence we will not repeat this information here.

Adding your own wizard steps

You can easily add or remove steps to the wizard.

Create a step class

The easiest would be to start from one of our bundled steps. A step usually will inherit from

\MarvinLabs\SetupWizard\Steps\BaseStep
and must implement a few more methods.

getFormData()

This is the data which will be passed to your view. If you do not specify that method, it will return an empty array. The data you pass in this array will be available in the step view directly as a variable. For example, if you return

[ 'myVar' => 23 ]
, you will be able to access
$myVar
in your step view.

apply($formData)

The method which is called before moving on to the next step. The

$formData
parameter contains the data that has been submitted with the step form (if any).

That method should return

true
if the wizard can proceed to the next step. If not, it should return
false
and can provide user feedback by using the method
$this->addError('my_key', 'My error message')
.

undo()

The method is called when coming back to this step from the next one. This basically undoes everything that has been done by the

apply
method.

That method should return

true
if the wizard can come back to our step. If not, it should return
false
and can provide user feedback by using the method
$this->addError('my_key', 'My error message')
.

Create the step view

If you have registered your step class with the id

my_step
, you need to create a view which will be found in the file
resources/views/vendor/setup_wizard/partials/steps/my_step.blade.php
.

Create the strings

Some strings are required for the step to be properly displayed: icon, title, description, etc. These can be found in the file

resources/lang/en/steps.php
. You will notice that each step ID contains a few strings which provide this information.

Add your step to configuration

Open

config/setup_wizard.php
and add your step class to the list of steps for the wizard:
    'steps' => [
        'requirements' => \MarvinLabs\SetupWizard\Steps\RequirementsStep::class,
        'folders'      => \MarvinLabs\SetupWizard\Steps\FoldersStep::class,
        'env'          => \MarvinLabs\SetupWizard\Steps\EnvFileStep::class,
        'database'     => \MarvinLabs\SetupWizard\Steps\DatabaseStep::class,

    'my_step'      => \App\Setup\MyStep::class',

    'final'        => \MarvinLabs\SetupWizard\Steps\FinalStep::class,
],

The steps are declared in the order in which they will be run. You can of course remove some of the default steps. However, you should always finish the wizard with the FinalStep. That step will write a file which will prevent the setup wizard to be executed again once done. This provides security as nobody will be able to run the setup again if the

storage/.setup_wizard
file is there.

Credits

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.