Invigor User Management Package

This package provide the fundamental functionality of user management, including CRUD of users, groups, roles, permissions and relationships between each of them.

Please check System/Project requirements and Assumptions before using this package.

---

###Table of Content

• System/Project requirements and Assumptions
• Installation Guide
  • composer.json - repo
  • composer.json - require-dev
  • composer update
  • config/app.php - provider
  • config/app.php - alias
  • User model adds UMUserTrait
  • Generate controllers
  • Generate migration
  • Migrate UM DB tables
  • Generate seeder and seeding
  • vendor:publish - views
  • Create view layout
  • Required front-end resources
• Default Package Routes
  • Default routes
  • User routes
  • Group routes
  • Role routes
  • Permission routes
• Controllers
  • Controllers in UM package
  • Controllers in app folder
• Middleware
  • Sample usage of role in routes
  • Sample usage of permission in routes
  • Sample usage of ability in routes
  • Sample usage of middleware in controllers
• Default data
• Entity relationships

---

###System/Project Requirements and Assumptions

1. Project is using PHP Laravel version-5.2.*.
2. Project is using either array, redis, memcached or other tagging supported caching system
3. Project is using default User model provided by Laravel.

Please be noticed that modification or customisation in default User model might require changes in the views, routes or controllers provided by this package. Will explain in detailed in this article.

---

###Installation Guide

In your Laravel project,

1.Add a repository to composer.json file repositories array.

{
    "repositories": [
        {
            "type": "vcs",
            "url": "ssh://[email protected]:234/srv/repo/git/invigor-user-management"
        }
    ]
}

---

2.Add a dev requirement to require-dev in composer.json.

{
    "require-dev": {
      "invigor/um": "dev-master"
    }
}

---

3.Run composer update in project root folder.

---

4.Add the following code to providers array in config/app.php

Invigor\UM\UMServiceProvider::class,

---

5.Create aliases in config/app.php by adding following code to aliases array

'UM' => Invigor\UM\UMFacade::class,
'role' => Invigor\UM\Middleware\UMRole::class,
'permission' => Invigor\UM\Middleware\UMPermission::class,
'ability' => Invigor\UM\Middleware\UMAbility::class,

---

6.Use user trait in default User model:

use Invigor\UM\Traits\UMUserTrait;

class User ...
{
    use UMUserTrait;
    
    ...
    ...
}

---

7.Generate controllers, in root folder of the project run:

php artisan um:controller

---

8.Generate migration files, in root folder of the project run:

php artisan um:migration

---

9.Migrate database tables

php artisan migrate

---

10.Generate seeder and proceed seeding

php artisan um:seeder

This seeder will insert default records into Database. Please refer to Default Data.

---

11.Include views

UM package provides comprehensive views to take care of CRUD of entities. By running the following command in root folder of the project, a um folder with views will be copied over to resources/views folder

php artisan vendor:publish

Developers are suggested to create their own layouts and extend the layouts in the view.

um
|---user
|----|---index.blade.php
|----|---create.blade.php
|----|---edit.blade.php
|----|---show.blade.php
|---group
|----|---index.blade.php
|----|---create.blade.php
|----|---edit.blade.php
|----|---show.blade.php
|---role
|----|---index.blade.php
|----|---create.blade.php
|----|---edit.blade.php
|----|---show.blade.php
|---permission
|----|---index.blade.php
|----|---create.blade.php
|----|---edit.blade.php
|----|---show.blade.php

---

12.View Layout

The views described in 11 do NOT include any CSS nor JS resources.

Therefore, a layout with required front-end resources is essential in order to use the default views. modify the view to extend the layout you have created.

The required front-end resources will be specified in 13

layout:

<link href="the_required_css_styles" />
<script src="the_required_js"></script>

views generated by vendor:publish

@extends('the_layout_you_have_created')

{{--default view content--}}
......
...
.

---

13.Required Front-end Resources

The default views of UM package required a few front-end resources.

• jQuery
• Bootstrap
• DataTables
• Select2

If your project does not have the resource specified above ready, please proceed with the following installation.

#install jQuery
$ npm install jquery
#install Bootstrap 3 
$ npm install bootstrap@3
#install DataTables
$ npm install datatables.net
#install DataTables Bootstrap theme
$ npm install datatables.net-bs
#install Select2
$ npm install https://github.com/select2/select2.git

And make sure the following resource are included sequentially

[
  "node_modules/jquery/dist/jquery.js",
  "node_modules/bootstrap/dist/js/bootstrap.js",
  "node_modules/datatables.net/js/jquery.dataTables.js",
  "node_modules/datatables.net-bs/js/dataTables.bootstrap.js",
  "node_modules/select2/dist/js/select2.js"
]

[
  "node_modules/bootstrap/dist/css/bootstrap.css",
  "node_modules/datatables.net-bs/css/dataTables.bootstrap.css",
  "node_modules/select2/dist/css/select2.css"
]

And make sure font files of Bootstrap is in a fonts folder, a sibling folder of where bootstrap.css sits

---

Now the package is good to go.

---

###Default Package Routes

#####Default routes

get:um/home is a default and temporary home page of User Management package, it includes a very plain login form if user is not yet logged in.

get:um/login is a plain login form connect to a customised Authentication Controller in the package.

#####User routes

get:um/user is a list page of users.

get:um/user/{id} is a detail page of a selected user.

get:um/user/create is the create page of user.

post:um/user insert a record in users table.

get:um/user/{id}/edit is the edit page of a selected user.

put/patch:um/user/{id} updates a record in users table.

delete:um/user/{id} deletes a record in users table.

#####Group routes

get:um/group is a list page of groups.

get:um/group/{id} is a detail page of a selected group.

get:um/group/create is the create page of group.

post:um/group insert a record in groups table.

get:um/group/{id}/edit is the edit page of a selected group.

put/patch:um/group/{id} updates a record in groups table.

delete:um/group/{id} deletes a record in groups table.

#####Role routes

get:um/role is a list page of roles.

get:um/role/{id} is a detail page of a selected role.

get:um/role/create is the create page of role.

post:um/role insert a record in roles table.

get:um/role/{id}/edit is the edit page of a selected role.

put/patch:um/role/{id} updates a record in roles table.

delete:um/role/{id} deletes a record in roles table.

#####Permission routes

get:um/permission is a list page of permissions.

get:um/permission/{id} is a detail page of a selected permission.

get:um/permission/create is the create page of permission.

post:um/permission insert a record in permissions table.

get:um/permission/{id}/edit is the edit page of a selected permission.

put/patch:um/permission/{id} updates a record in permissions table.

delete:um/permission/{id} deletes a record in permissions table.

---

###Controllers

There are two sets of controllers:

1. The controllers inside UM package.

2. The controllers generate by UM package and sit in app\Http\Controllers\UM folder.

#####Controllers in UM package

The controllers mainly provide functions of CRUD of user, group, role and permission.

The index function of the controllers takes a parameter to indicate the expected output format: "datatable" or null. "datatable" takes corresponding request values and filters the result accordingly. While null value outputs all records of the entities.

All functions in controllers in UM package do not deal with views nor routes.

In order to provide good enough flexibility to this package, data validations of create and update functions are in Controllers in app folder.

#####Controllers in app folder

The controllers in app folder take care of the routes, views and representation of data.

By default, the controllers are pointing to the views in resources/views/um. However, this can be changed directly in the controllers in app folder.

---

###Middleware

There are three main types of middleware available in the package.

• role
• permission
• ability (used only in a complicated situation)

All middleware can be set in routes file or controllers. And here are the usages.

#####Sample usage of role in routes:

Route::get('url', ['middleware' => ['role:super_admin|client']])

super_admin and client are the name of roles (NOT display_name)

In this case, only the users with role super_admin OR client can access this route.

#####Sample usage of permission in routes:

Route::get('url', ['middleware' => ['permission:create_user|edit_user']])

create_user and edit_user are the name of permissions (NOT display_name)

This route only open to the users with permission of create_user OR edit_user.

#####Sample usage of ability in routes:

Route::get('url', ['middleware' => ['ability:super_admin|client,create_user|edit_user', true]])

This middleware takes three (3) parameters, including roles, permissions and operator.

Operator is a boolean (true/false) indicating if middleware needs to validate both roles and permissions or not.

In this case, the route only open to the super_admin OR client with the permissions of create_user OR edit|user.

#####Sample usage of middleware in controllers:

$this->middleware('role:super_admin, ['only' => ['create', 'store']]');
$this->middleware('permission:create_user', ['only' => ['create', 'store']]);
$this->middleware('ability:super_admin,create_user,true', ['only' => ['create', 'store']]);

Syntax is pretty much same as middleware in route. However, we need to indicate which functions the middleware shall be applied to by having ['only' => [blah blah blah] as the second parameter in the middleware functions.

---

###Default Data

Initial seeder will insert the following records:

#####users table

a user with super_admin role and all parent permissions.

email: [email protected]

password: secret

#####groups table

seeder does not insert any default group record

#####roles table

seeder inserts a super_admin record to database.

#####permissoins table

by default, seeder inserts CRUD permissions to 4 entities, and parent permissions for each entity:

manage_user
    |--------create_user
    |--------read_user
    |--------update_user
    |--------delete_user
manage_group
    |--------create_group
    |--------read_group
    |--------update_group
    |--------delete_group
manage_role
    |--------create_role
    |--------read_role
    |--------update_role
    |--------delete_role
manage_permission
    |--------create_permission
    |--------read_permission
    |--------update_permission
    |--------delete_permission

---

###Entity Relationships

• group-user: many to many

  a group can have multiple users, and a user can be in multiple groups.

• user-role: many to many

  a user can be in multiple roles, and multiple users can be in the same role.

• role-permission: many to many

  a role can have multiple permissions, and multiple roles can have the same permission.

• permission-permission: one to many

  multiple permissions can have a parent permission.