Download the PHP package michele-angioni/phalcon-confer without Composer

Confer

Introduction

Phalcon Confer, or simply Confer, empowers your application of a powerful yet flexible Roles and Permissions management system.

Either Users or User Teams can receive new Roles.

Confer has been highly inspired by the Laravel package Entrust.

Installation

Confer can be installed through Composer, just include "michele-angioni/phalcon-confer": "^1.0" to your composer.json and run composer update or composer install.

Then Confer migrations must run to create the needed tables. For this, you need to have installed the Phalcon Dev Tools.

Alternatively, Yarak can be used to run the migrations. Just copy-paste the migration files into your migration folder and run php yarak migrate.

From your Phalcon document root, just run phalcon migration run --migrations=vendor/michele-angioni/phalcon-confer/migrations .

Usage

Empowering Users

Let's say you have a MyApp\Users model you want to add roles to. It just needs to extend MicheleAngioni\PhalconConfer\Models\AbstractConferModel and use MicheleAngioni\PhalconConfer\ConferTrait like so:

Empowering Teams

Alternatively, if your application has User Teams and you need to empower Teams of a Roles and Permission system, Confer can do it.

Let's say you also have a MyApp\Teams model and you want to add roles to Users separately for each Team they belong. You just need to also extend MicheleAngioni\PhalconConfer\Models\AbstractConferTeamModel and the MicheleAngioni\PhalconConfer\ConferTeamTrait to your Team model like so:

Roles and Permission Management

The Confer Class

Most of Confer features can be handled through the Confer class, which provides a useful gateway to manage Roles and Permissions.

You can create an instance of the Confer class simply with

or you can take advantage of Phalcon's Dependency Injection, by defining

Retrieving all Roles and Permissions

Thanks to the Confer class retrieving all Roles and Permissions is straightforward

Retrieving a specific Role or Permission

The Confer class allows also to search a Role or a Permission by both id and name

Creating a new Role

Creating a new Role is simple and can be done again by using the Confer class

Creating a new Permission

Creating a new Permission is done in the same way of a Role

Deleting a Role or Permission

The Confer class is also provided with methods to properly delete Roles and Permissions by id and name.

Assigning a Permission to a Role

Assigning a Permission to a Role is straightforward

Removing a Permission from a Role

Same as before, removing a Permission from a Role is achieved with a single command

Retrieving all Permission Roles

Thanks to the Phalcon ORM, we can immediatly retrieve all Permission from a Role

User Roles Management

Assigning a Role to a User

Thanks to the ConferTrait, managing roles is extremely simple with Confer

Removing a Role from a User

In a way similar to the assignment, we can remove it

Retrieving all User Roles

Again, thanks to the Phalcon ORM, we can immediatly retrieve all Roles from a User

Checking for a Role

Checking if a User has a specific Role is straightforward

Checking for a Permission

Even checking for a specific Permission is super easy

Team User Roles Management

Assigning a Role to a Team

Thanks to the ConferTeamTrait, even Team Roles can be handled without efforts

Removing a Role from a Team

In a way similar to the assignment, we can remove it

Checking for a Role

Checking if a Team User has a specific Role can be done both from the User and Team models

Checking for a Permission

Also checking for a specific Permission can be performed from both models

Middlewares

Once you have set your own Roles and Permissions, it is likely you want to protect some of your routes. The simplest way to achieve that is to use the Match feature of the Phalcon Router. You can easily write your custom RolesMiddleware or use the one included in Confer.

Custom Match Middleware

Let's build a custom RolesMiddleware skeleton so you can easily add it to your application

Now that we have our RolesMiddleware, just add it to the router and check if the user has the 'Admin' Role

That's it. If the User has not the required Role, he/she will get a 404 error.

Confer RolesMiddleware

Confer comes with an own RolesMiddleware out of the box. However, in order to use it, the User authentication must be handled by Phalcon Auth.

Phalcon Auth allow you to easily retrieve the authenticated user by just calling $auth->getAuth().

If you are using Phalcon Auth to handle your authentication, adding the Confer RolesMiddleware is straightforward

Contribution guidelines

Confer follows PSR-1, PSR-2 and PSR-4 PHP coding standards, and semantic versioning.

Pull requests are welcome.

License

Confer is free software distributed under the terms of the MIT license.