Tutorial 6: How to Build a Laravel 5.4 Administration Module with Role-based permissions using Entrust package. (Part 1)

In this tutorial, we will be building an Administration Module with an ACL(Access Control List) based on Roles and Permissions.

This module will be modelled after a recruitment agency software, to keep it simple, we will have 3 different types of users (roles), using the Entrust package, we will control the sections each type of user has access to.

User Roles

1. Administrator — The admin can add new users and roles. The admin can also set the permissions for each role and assign a role to a specific user.
2. Senior Consultant — This user can only add, view, update and delete clients, jobs and candidates but cannot add new users or carry out any of the other functionalities available to the admin.
3. Junior Consultant — This user can add, view, update and delete jobs and candidates. This user can also view clients but cannot add, update or delete clients.

Permisssions

1. Roles (Create role, view all roles, update role, delete role)
2. Users (Create user, view all users, update user and its role, delete user)
3. Clients (Create client, view all clients, update client and delete client)
4. Jobs (Create jobs, view all jobs, update job and delete job)
5. Candidates (Create candidates, view all candidates, update candidate and delete candidate)

Roles and Permission

1. Admin (create role, view all roles, update role, delete role, create user, view all users, update user, delete user)
2. Senior Consultant (create client, view all clients, update client, delete client, create jobs, view all jobs, update job, delete job, create candidates, view all candidates, update candidate and delete candidate)
3. Junior Consultant (view all clients, create jobs, view all jobs, update job, delete job, create candidates, view all candidates, update candidate and delete candidate)

Please note that this tutorial assumes you have some PHP experience, this tutorial does not explain each line of the code instead it presents you with the code and gives you an overview of what the code does and points out the important parts of the code. I have made the code as simple as possible, if you have any questions, please do not hesitate to leave a comment.

Step 1: Create new project and install Entrust

Create Laravel project

laravel new administration-module

Install Entrust

Open composer.json and update the require object to include entrust

composer.json

Then run

composer update

Step 2: Add Entrust Provider and Facades

Open up config/app.php, find the providers array and add the entrust provider:

Zizaco\Entrust\EntrustServiceProvider::class,

Find the aliases array and add the entrust facades:

'Entrust'   => Zizaco\Entrust\EntrustFacade::class,

Run the command below from the command line to publish the package config file.

After you run this command you will see a new file in the config directory called entrust.php.

Entrust package provides it’s in-built middleware that way we can use it, open app/Http/Kernel.php and add the middleware.

Kernel.php

Now that the installation is done, lets move on to creating our database tables.

Step 3: Set Up Database

For this project we will be creating the following tables:

1. roles — stores role records
2. permissions — stores permission records
3. role_user — stores many-to-many relations between roles and users
4. permission_role — stores many-to-many relations between roles and permissions
5. users
6. clients
7. jobs
8. candidates

This first 4 tables are part of the Entrust package and are created with the entrust migration file which can be generated by running the command below.

php artisan entrust:migration

This command generates the entrust migration file (<timestamp>_entrust_setup_tables.php) in the database/migrations directory. The file will contain the following code so you don’t need to do anything to it.

<timestamp>_entrust_setup_tables.php

Thankfully, Laravel ships with a migration file to create a basic users table, so we do not need to manually generate one. We need to manually generate the migration file for the remaining tables.

php artisan make:migration create_clients_table
php artisan make:migration create_jobs_table
php artisan make:migration create_candidates_table

Now, lets update our freshly generated migration files.

clients

jobs

candidates

I have kept the tables as basic as possible, you can add additional column to each table to indicate other information such as the client status (hiring/not hiring), job type (part time/ full time/ contract etc), job location, candidates preferred job type (part time/ full time/ contract etc), candidates status (looking/not looking) etc…

With our migration file ready, lets update our database settings. Rename the .env.example file to .env or copy and paste the file and rename to .env. Update the database settings and update the CACHE_DRIVER value to array.

.env

Make sure to run php artisan key:generate after this in order to create an application key

If you are using MAMP be sure to add the unix_socket key with a value of the path that the mysql.sock resides in MAMP. Open config/database.php

config/database.php

And run migration

php artisan migrate

if you get the error below

[Illuminate\Database\QueryException] SQLSTATE[42000]: Syntax error or access violation: 1071 Specified key was too long; max key length is 767 bytes (SQL: alter table `users` add unique `users_email_unique`(`email`))
SQLSTATE[42000]: Syntax error or access violation: 1071 Specified key was too long; max key length is 767 bytes

Open up Providers/AppServiceProvider.php and update the boot function

Providers/AppServiceProvider.php

Your database should now look like the image below.

Now that our database is ready, lets create our Models.

Step 4: Create Models

The first thing we will do is create the Models for our Roles, Permissions, Users, Clients, Jobs and Candidates table. Run the command below to generate the Model files.

php artisan make:model Role
php artisan make:model Permission
php artisan make:model Client
php artisan make:model Job
php artisan make:model Candidate

Update the generated files located in the app directory

Role

Permission

Permission.php

Both Role and Permission model have the same three attributes:

• name — Unique name for the role/permission, used for looking up role/permission information in the application layer.
• display_name — Human readable name for the role/permission. Not necessarily unique and optional.
• description — A more detailed explanation of the Role/Permission.

See Entrust Github page for more info.

User — this file should have been generated when you created the project, if not generate the file using the make:model command. Update the current code by adding line 7 and 13

User.php

Client

Job

Candidate

Step 5: Create Our Database Seeder

Next, we will create our permission seeder file in order to populate the database with our permissions. Run the following code to create the seeder file.

php artisan make:seeder PermissionSeeder

The PermissionSeeder.php file will be generated in the database/seeds directory. Update the file with the code below:

PermissionSeeder.php

Run the code below to populate the permissions table.

php artisan db:seed --class=PermissionSeeder

Next, we will update our DatabaseSeeder.php in order to create our Admin Role and Admin user. Update the file with the code below:

Run the code below to populate the role and user table with our admin role and user.

php artisan db:seed --class=DatabaseSeeder

This is the end of part one, so far we have we created our project, installed and configured the Entrust package, created and seeded our database and created our Models.

Check out part two to continue.

Thats all folks!