Admin Generator

• Requirements
• Installation
• Usage
  • Authorization (without Craftable)
  • Columns API
  • Form generators
  • Listing generator
  • Validation rules generators
  • Export support
• User generators

Admin Generator is a package that helps you quickly scaffold your typical CRUD admin interfaces. It generates the code based on the existing (migrated) table in the database. It uses an admin UI template from our other package brackets/admin-ui.

Requirements

This package requires PHP 7.1+ and Laravel (5.5, 5.6 or 5.7).

It has no dependency itself, but it generates a code dependent on these package:

• brackets/admin-ui
• brackets/admin-listing
• brackets/admin-auth (optionally, depending on a database structure)
• brackets/translatable

So if you are installing this package on your own (outside brackets/craftable), you have to correctly install all these packages before. See installation instructions for these packages:

• Admin UI
• Admin Listing
• Admin Auth
• Translatable

Installation

{danger.fa-exclamation-triangle} This section is only when you want to use this package as a standalone package. If you are using with Craftable, then this package is already installed.

Installation is straightforward - let's add a new dev requirement:

composer require --dev brackets/admin-generator

That's it. Provider will be discovered automatically (and only in development).

Usage

Generator provides several useful commands to quickly scaffold your CRUD:

• admin:generate:model Generate a model class
• admin:generate:controller Generate a controller class
• admin:generate:index Generate an index view template
• admin:generate:form Generate create and edit view templates
• admin:generate:factory Append a new factory
• admin:generate:routes Append admin routes into a web routes file
• admin:generate:request:index Generate an Index request class
• admin:generate:request:store Generate a Store request class
• admin:generate:request:update Generate an Update request class
• admin:generate:request:destroy Generate a Destroy request class
• admin:generate:permissions Generate a default permissions migration

Typically you would not use any of the commands above, because typically you just want to generate whole CRUD interface with all that stuff. So here's another command:

• admin:generate Scaffold complete CRUD admin interface

which basically runs all the commands above in one run.

Let's see it in action. All the commands requires a migrated table to be present in the database. Imagine you have table posts created with this migration:

Schema::create('posts', function (Blueprint $table) {
    $table->increments('id');
    $table->string('title');
    $table->string('slug')->unique();
    $table->text('perex')->nullable();
    $table->date('published_at')->nullable();
    $table->boolean('enabled')->default(false);
    $table->timestamps();
});

Now we need to migrate this table:

php artisan migrate

We are ready to generate the Post model and whole CRUD interface for Posts using command:

php artisan admin:generate posts

If yoou are using this package with brackets/craftable, then you will be prompted to migrate generated migration that attaches permissions to the default role. It's safe to choose yes. If you choose no, then you need to migrate this permission on your own or define generated admin abilities (see Authorization (without Craftable) for inspiration).

{danger.fa-exclamation-triangle} Note that if you are using this package as a standalone package (without brackets/craftable), then you must follow Authorization (without Craftable) steps, otherwise you will get an authorization error when trying to reach the CRUD.

{info} We love to organize things that's why we have changed the default namespace for models to App\Models. But you can always specify any other (i.e. Laravel's default App\) with a -m option.

{info} You can also run admin:generate command with --seed option to seed some fake data.

Finally we need to re-compile all the assets:

npm run dev

Now you can refresh your admin interface in a browser. You should be able to see new menu item Posts.

Columns API

Generator supports these Blueprint types in your migrations:

• string
• text
• number
• date
• datetime
• time
• jsonb (special meaning, see below)
• boolean

Other types are allowed, but treated as string type.

Form generators

Generator supports these types of form elements:

• input text (for any string or other column)
• textearea (for any text)
• wysiwyg (when column name is one of: text, body, description)
• date (for any date)
• datetime (for any datetime)
• time (for any time)
• number (for any number)
• translatable column (for any jsonb)
• checkbox (for any boolean)

Primary key as well as some system columns are excluded (i.e. created_at, updated_at, ...) from the forms.

Listing generator

Generators includes all the columns in the listing except:

• columns of text type
• columns of jsonb type (when name is one of: perex, text or body)
• some system columns (i.e. created_at, updated_at, password, ...)

If column name is one of: enabled, activated or is_published and this column is of boolean type, then it will be automatically generated as a switch element.

Validation rules generators

Generator generates also a validation rules for store and update requests. Types reflects standard validation rules defined in Laravel.

Not setting nullable on column makes the attribute required on store request and sometimes on update request.

Column named email gets a proper email validation rule.

Export support

Generator provides --with-export parameter that generates the ability to Export data as .xlsx. Generator generates a [ModelName]Export class within App/Export directory that provides several options (i.e. attributes to export, formatting, etc.). For more information see the documentation of Laravel Excel.

Authorization (without Craftable)

{info} This section is for those of you who use this package as a standalone package (without brackets/craftable) or does not want to use the default permissions and roles provided by this generator. Otherwise, you can safely skip this chapter :)

For security reasons generator generates a routes that are protected with 4 different abilities:

• admin.model-name.index
• admin.model-name.create
• admin.model-name.edit
• admin.model-name.destroy

In case you are using this package as standalone package or in case you have choosen not to migrate generated permissions, then the definition of these abilities is left to you - to meet your use case.

Let's quickly define new abilities, that temporarily allows any authenticated user to access the Post admin CRUD, just for a demonstration. So let's edit App\Providers\AuthServiceProvider:

class AuthServiceProvider extends ServiceProvider
{
    ...
    public function boot()
    {
        ...
        // we return true for any $user that is passed to these abilities
        Gate::define('admin.post.index', function ($user) { return true; });
        Gate::define('admin.post.create', function ($user) { return true; });
        Gate::define('admin.post.edit', function ($user) { return true; });
        Gate::define('admin.post.delete', function ($user) { return true; });

{danger.fa-exclamation-triangle} In real project be aware of exposing your CRUD to anybody. You should perform real checks (i.e. check if user is really an administrator).

After authorization correctly set up, everything is ready to use.

User generators

There are two more special commands for an atypical User model CRUD and for scaffolding My profile functionality in the Administration area.

• admin:generate:user Scaffold complete admin CRUD for specified user model. This differs from admin:generate command in many additional features (password handling, roles, ...).
• admin:generate:user:profile Scaffold admin "My Profile" feature (controller, views, routes)

Let's see it in action. In your project you typically already have an User model class. Let's assume it is not placed in package's default directory app\Models (but in Laravel's default app\), we have to pass the path to the command:

php artisan admin:generate:user --model-name="App\User"

Command generates all the CRUD like normal generator. But it adds some features:

• if you use brackets\admin-auth it is going to generate a code for a features: Activation, Block access
• if you use spatie/laravel-permissions it is going to generate an ability to assign roles to the user model
• couple of other improvements

The second command is going to quickly scaffold standard My profile functionality:

php artisan admin:generate:user:profile --model-name="App\User"