Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/ycs77/laravel-wizard

A web Setup Wizard for Laravel application.
https://github.com/ycs77/laravel-wizard
laravel laravel-wizard wizard-steps
Last synced: 22 days ago
JSON representation
A web Setup Wizard for Laravel application.
Host: GitHub
URL: https://github.com/ycs77/laravel-wizard
Owner: ycs77
License: mit
Created: 2019-06-08T10:51:36.000Z (over 5 years ago)
Default Branch: 4.x
Last Pushed: 2024-09-17T03:21:00.000Z (2 months ago)
Last Synced: 2024-10-15T08:41:18.445Z (about 1 month ago)
Topics: laravel, laravel-wizard, wizard-steps
Language: PHP
Homepage:
Size: 311 KB
Stars: 122
Watchers: 5
Forks: 18
Open Issues: 0
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project

README

        # Laravel Wizard

[![Latest Version on Packagist][ico-version]][link-packagist]

[![Software License][ico-license]](LICENSE)

[![GitHub Tests Action Status][ico-github-action]][link-github-action]

[![Style CI Build Status][ico-style-ci]][link-style-ci]

[![Total Downloads][ico-downloads]][link-downloads]

A web setup wizard for Laravel application.

> This package is adapted from [smajti1/laravel-wizard](https://github.com/smajti1/laravel-wizard).

![Laravel wizard main image.](docs/laravel-wizard-main-image.jpg)

## Table of Contents

- [Laravel Wizard](#laravel-wizard)

  - [Table of Contents](#table-of-contents)

  - [Version Compatibility](#version-compatibility)

  - [Installation](#installation)

  - [Usage](#usage)

    - [1. Generate controller and wizard steps](#1-generate-controller-and-wizard-steps)

    - [2. Set steps](#2-set-steps)

    - [3. Install wizard steps CSS package](#3-install-wizard-steps-css-package)

  - [Cache](#cache)

    - [Database Driver](#database-driver)

    - [Disable Cache](#disable-cache)

  - [Controller](#controller)

    - [Setting Configuration](#setting-configuration)

  - [Customize View](#customize-view)

  - [Step](#step)

    - [Get cached data](#get-cached-data)

    - [Redirect to the step](#redirect-to-the-step)

    - [Step repository](#step-repository)

    - [Upload Files](#upload-files)

    - [Skip step](#skip-step)

    - [Passing data to views](#passing-data-to-views)

    - [Save data on another step](#save-data-on-another-step)

    - [Set relationships model](#set-relationships-model)

    - [Force restart from first step](#force-restart-from-first-step)

  - [Commands](#commands)

  - [Sponsor](#sponsor)

  - [Credits](#credits)

  - [License](#license)

## Version Compatibility

| Laravel Wizard | Laravel              | PHP              |

| -------------- | -------------------- | ---------------- |

| 1.0.x          | 5.5                  | ^7.0             |

| 1.1.x          | ^5.6                 | ^7.1.3           |

| 2.0.x,2.1.x    | ^5.6 \| ^6.x         | ^7.1.3           |

| 2.2.x          | ^5.6 \| ^6.x \| ^7.x | ^7.1.3           |

| 2.3.x          | >=5.6 \| <=9.0       | >=7.1.3 \| <=8.2 |

| 3.x            | >=9.0                | >=8.1            |

| 4.x            | >=11.0               | >=8.2            |

## Installation

Install the package via composer:

```bash

composer require ycs77/laravel-wizard

```

Publish config:

```bash

php artisan vendor:publish --tag=wizard-config

```

## Usage

### 1. Generate controller and wizard steps

Now you can qckly generate the wizard controller and the wizard steps:

```bash

php artisan make:wizard User NameStep,EmailStep

```

This command generates the `UserWizardController`, `NameStep`, and `EmailStep` class, and appends the wizard route to `routes/web.php`.

*routes/web.php*

```php

use App\Http\Controllers\UserWizardController;

use Illuminate\Support\Facades\Route;

use Ycs77\LaravelWizard\Facades\Wizard;

...

Wizard::routes('/wizard/user', UserWizardController::class, 'wizard.user');

```

> If you can't use auto append route, you can set `config/wizard.php` attribute `append_route` to `false`.

### 2. Set steps

This is generated NameStep class, you can to `model` method set the model, to `rules` method set form validation, and save `$data` to your database via the `saveData` method, for example:

*app/Steps/User/NameStep.php*

```php

update($data);

    }

    /**

     * Validation rules.

     *

     * @param  \Illuminate\Http\Request  $request

     * @return array

     */

    public function rules(Request $request)

    {

        return [

            'name' => 'reqred',

        ];

    }

}

```

And add some steps view, for example:

*resources/views/steps/user/name.blade.php*

```blade



    Name

     $errors->has('name')]) value="{{ old('name', $step->data('name')) }}">

    @error('name')

        {{ $message }}

    @enderror



```

*resources/views/steps/user/email.blade.php*

```blade



    E-mail

     $errors->has('email')]) value="{{ old('email', $step->data('email')) }}">

    @error('email')

        {{ $message }}

    @enderror



```

Next, browse the URL `/wizard/user`, and start to use the Laravel Wizard.

> If you want to get the layout you can copy [Laravel  layouts/app.blade.php](https://github.com/laravel/ui/blob/4.x/src/Auth/bootstrap-stubs/layouts/app.stub) to `resources/views/layouts/app.blade.php`

### 3. Install wizard steps CSS package

The CSS for this package default view is based on the [Bootstrap Steps](https://github.com/ycs77/bootstrap-steps), use NPM installation to use:

```bash

npm install bootstrap bootstrap-steps

// or yarn

yarn add bootstrap bootstrap-steps

```

Import to the `app.scss` file and run `npm run dev` or `yarn run dev`:

*resources/sass/app.scss*

```scss

...

@import 'bootstrap/scss/bootstrap';

@import 'bootstrap-steps/scss/bootstrap-steps';

```

## Cache

### Database Driver

To use the `database` wizard cache driver, you will need a database table to hold the cache data of the wizard. Generate a migration that creates this table, and runs the `wizard:table` Artisan command:

```

php artisan wizard:table

php artisan migrate

```

### Disable Cache

Set `cache` in `config/wizard.php` to `false` to disable cache input data:

```php

'cache' => false,

```

Or set it to your WizardController `wizardOptions` property:

```php

protected $wizardOptions = [

    'cache' => false,

];

```

If disabled cache, the data will be saved in the data immediately after each step is sent. If you are afraid to save the data repeatedly, you can hide the Prev button, or use `Model::updateOrCreate()` (https://laravel.com/docs/6.x/eloquent#other-creation-methods).

## Controller

### Setting Configuration

Add `wizardOptions` property to your wizard controller, you can use the `cache`, `driver`, `connection`, and `table` options to override configuration.

*app/Http/Controllers/UserWizardController.php*

```php

/**

 * The wizard options.

 *

 * @var array

 */

protected $wizardOptions = [

    'cache' => true,

    'driver' => 'session',

    'table' => 'wizards',

];

```

## Customize View

This package layout view uses Bootstrap 5, but if you don't want to use default views, you can publish views to custom it:

```bash

php artisan vendor:publish --tag=wizard-views-bs5

```

If you used Bootstrap 4, you could publish the layouts:

```bash

php artisan vendor:publish --tag=wizard-views-bs4

```

If you used Tailwind CSS, you could publish the layouts:

```bash

php artisan vendor:publish --tag=wizard-views-tailwind

```

Now you can customize `resources/views/vendor/wizard/*.blade.php` in your Laravel project.

But if you want a custom-only one wizard view base view, you can copy the views from `resources/views/vendor/wizard/*.blade.php` to `resources/views/wizards/user/*.blade.php`. (`user` is `wizardName` property value on your wizard controller),

## Step

### Get cached data

For example, `FirstStep` has `name` and `email` fields, and `SecondStep` has `age` and `phone` fields. you can use the `data` method of step to get step data:

```php

$name = $firstStep->data('name');

// 'Lucas'

$data = $secondStep->data();

// ['age' => '30', 'phone' => '0900111222']

```

Or you can use the step repository to get other step data:

```php

$data = $secondStep->find('first')->data();

// ['name' => 'Lucas']

$name = $secondStep->find('first')->data('name');

// 'Lucas'

```

### Redirect to the step

If you want to manually redirect to another step, you can use the `redirectToStep()` of the wizard, it will return a redirect response.

```php

// given a step slug

return $wizard->redirectToStep('second');

// given a step insatnce

return $wizard->redirectToStep($secondStep);

```

### Step repository

Step repository saves all steps data, if you want to use another step, you need to use it:

From wizard:

```php

$stepRepo = $wizard->stepRepo();

```

From step:

```php

$stepRepo = $step->getRepo();

```

Get the previous step:

```php

$prevStep = $step->prev();

// same as:

$prevStep = $step->getRepo()->prev();

```

Get the next step:

```PHP

$prevStep = $step->next();

// same as:

$nextStep = $step->getRepo()->next();

```

Step repository all can use method detailed reference: [src/StepRepository.php](src/StepRepository.php)

### Upload Files

Since **v2.3.3** upload files in **Cache** and **No Cache** are supported, if use the **Cache Mode** you can cache all input data and uploaded files to save in the last step:

```php

user();

    }

    public function saveData(Request $request, $data = null, $model = null)

    {

        $data = [

            'avatar' => $this->find('has-avatar-step')->data('avatar'),

        ];

        $data['avatar'] = $data['avatar']->store('avatar', ['disk' => 'public']);

        $model->update($data);

    }

}

```

Then add a step view to upload the avatar image:

*resources/views/steps/user/has-avatar.blade.php*

```blade



    Avatar

     $errors->has('avatar')])>

    @error('avatar')

        {{ $message }}

    @enderror



```

### Skip step

> **Note**: **v2.3.3+**

To make Step skippable, set the `$skip` property to `true`, then this Step will skip the validation and save data:

*app/Steps/User/NameStep.php*

```php

    Select name

     $errors->has('name')])>

        Select...

        @foreach ($step->getOptions() as $option)

            data('name')))

            >

                {{ $option }}

            

        @endforeach

    

    @error('name')

        {{ $message }}

    @enderror

```

The `getOptions` method is custom and can be changed at will.

### Save data on another step

Suppose there are now two Steps `NameStep` and `EmailStep`.

First, don't set the Model for all Steps, but don't use the last one:

*app/Steps/User/NameStep.php*

```php

getStepsData();

        $model->fill($data)->save();

    }

}

```

### Set relationships model

Similarly, you can set the relationships model in the `model` method of the step.

```php

use Illuminate\Support\Arr;

/**

 * Set the step model instance or the relationships instance.

 *

 * @param  \Illuminate\Http\Request  $request

 * @return \Illuminate\Database\Eloquent\Model|\Illuminate\Database\Eloquent\Relations\Relation|null

 */

public function model(Request $request)

{

    return $request->user()->posts();

}

/**

 * Save this step form data.

 *

 * @param  \Illuminate\Http\Request  $request

 * @param  array|null  $data

 * @param  \Illuminate\Database\Eloquent\Model\Illuminate\Database\Eloquent\Relations\Relation|null  $model

 * @return void

 */

public function saveData(Request $request, $data = null, $model = null)

{

    $data = Arr::only($data, ['title', 'content']);

    $model->create($data);

}

```

### Force restart from first step

If you don't keep the cache on click the start wizard button, you can change the link to `/wizard/user?_reset=1`.

If you have any custom cache data you want to clean up, you can set the clean up into `cleanUpWizard()` hook in your `WizardController`, then it will clean on wizard done or visit route with `?_reset=1` parameter:

*app/Http/Controllers/UserWizardController.php*

```php

/**

 * Clean up the wizard event.

 *

 * @return void

 */

protected function cleanUpWizard(Request $request)

{

    // Cleanup wizard cache...

}

```

## Commands

**Make wizard**:

The `make:wizard` command and `make:wizard:controller` command difference, is `make:wizard` command will append the route and not confirm generate step.

```bash

php artisan make:wizard User NameStep,EmailStep

```

**Make controller**:

The `make:wizard:controller` command only generates the `WizardController`, `NameStep`, and `EmailStep` class.

```bash

php artisan make:wizard:controller UserController --steps=NameStep,EmailStep

```

**Make step**:

```bash

php artisan make:wizard:step NameStep

```

With step label and wizard:

```bash

php artisan make:wizard:step NameStep --label="Name" --slug=name --wizard=user

```

Add custom view path:

```bash

php artisan make:wizard:step NameStep --label="Name" --slug=name --view=steps.user.name --wizard=user

```

## Sponsor

If you think this package has helped you, please consider [Becoming a sponsor](https://www.patreon.com/ycs77) to support my work~ and your avatar will be visible on my major projects.



  

    

  





  



## Credits

* [smajti1/laravel-wizard](https://github.com/smajti1/laravel-wizard)

## License

[MIT LICENSE](LICENSE)

[ico-version]: https://img.shields.io/packagist/v/ycs77/laravel-wizard?style=flat-square

[ico-license]: https://img.shields.io/badge/license-MIT-brightgreen?style=flat-square

[ico-github-action]: https://img.shields.io/github/actions/workflow/status/ycs77/laravel-wizard/tests.yml?branch=4.x&label=tests&style=flat-square

[ico-style-ci]: https://github.styleci.io/repos/190876726/shield?style=flat-square

[ico-downloads]: https://img.shields.io/packagist/dt/ycs77/laravel-wizard?style=flat-square

[link-packagist]: https://packagist.org/packages/ycs77/laravel-wizard

[link-github-action]: https://github.com/ycs77/laravel-wizard/actions/workflows/tests.yml?query=branch%3A4.x

[link-style-ci]: https://github.styleci.io/repos/190876726

[link-downloads]: https://packagist.org/packages/ycs77/laravel-wizard