sorora/aurp

This package is abandoned and no longer maintained. No replacement package was suggested.

Aurp - Authentication for Users, Roles and Permissions in Laravel 4

dev-master 2014-12-11 09:19 UTC

Requires

• php: >=5.3.0
• illuminate/support: <4.2
• sorora/empower: dev-master

Requires (Dev)

• mockery/mockery: dev-master
• way/laravel-test-helpers: dev-master

MIT

• David Bowen

• Authentication
• auth
• laravel
• roles
• sorora

README

This package is no longer maintained, there are plenty of alternatives out there for laravel that do a great job.

What is Aurp?

Aurp is Authentication for Users, Roles and Permissions. It offers:

• Interfaces to do the following (with views that can be replaced by your own):
  • Add, Edit, View and Delete Permissions
  • Add, Edit, View and Delete Roles. Each role can have lots of permissions assigned to them, or just a few! It's up to you
  • Add, Edit, View and Delete Users. Each user has a role they belong to, allowing them to do certain things.
  • The "magicaurp" filter which uses RESTful key words to know if a user has permission to access a certain area
    • As long as routes follow the guide line of the Resource controllers, it'll work. Permissions should be named like (in this example, these define what the user can do with a page):
      • create_pages
      • edit_pages
      • show_pages
      • destroy_pages
    • The keyword should be pluralized to match the resource! For further information on magicaurp filter, see here
• The class "Aurp" can be used to know if a user can do a permission or permissions. It can be used to know if they cannot do a permission or permissions. It even can be used to know if a user is a certain role! Awesome eh?

In short, it adds interfaces (that can be customised) to your laravel installation that allow the management of users, roles and permissions. Login and logout functionality is also provided. This means, once installed, you don't need to code a thing!

Requirements

This package is created for Laravel 4 and uses the Auth class to reduce repetition.

It also requires the sorora/empower package, this will be installed when running composer update.

This package is solely for checking if users have certain permissions or are a certain role, and further information can be found in the usage section.

Installation

You can install this package via composer by adding the below to your composer.json file:

"sorora/aurp" : "dev-master"

Once you have installed the package via composer, see here to publish configuration/migrations for the packages in one command!

Note: You also need to add 'Sorora\Aurp\Providers\AurpServiceProvider' to your app/config/app.php file in the providers array

Configuration Options

Customisable Views

To see how to customise views / layouts used within this package, please see the README for the Empower package here

God Mode

Aurp's config.php option of godmode specifies what role has the power to do absolutely everything, ignoring all permissions. By default this is set to Super Admin but can be changed if you want.

Login/Logout Prefix

By default the login and logout routes are accessed via yoursite.com/login and yoursite.com/logout respectively. To add segments before these routes, simply change the prefix option in Aurps config.php file. By default it is set to false which means no segments are prepended to the route.

Usage

Once you have installed the package, published the config and migrated the tables, you can login to the admin panel via /login (assuming you have not prepended the route). A default user of [e-mail] with a password of password is provided for you, it is extremely important to change the password once you have logged in.

Once you are logged in, you should be on the main page of the administration panel (ensure you have added 'aurp' => 'layouts.nav' to Empowers externals config.php option), you will see a nav list of what you can do.

Aurp

Aurp can be accessed from your application with any of the commands below:

Is

is can be used to determine if a user is a specific role or not.

Example usage:

Aurp::is('Example Role');

Can

can can be used to determine if a user can do certain action(s). It accepts a single string or an array.

Example usage:

Aurp::can('create_permissions'); // returns true if the user has this permission, false if not.
Aurp::can(array('create_permissions', 'edit_permissions')); // returns true only if the user can do everything in the array

Cannot

cannot is used to determine if a user cannot do certain action(s). It accepts a single string or an array. This is the inverse of can.

Example usage:

Aurp::cannot('create_permissions'); // returns true if the user has not got this permission, false if they have.
Aurp::can(array('create_permissions', 'edit_permissions')); // returns true only if the user can not do everything in the array

Magicaurp Filter

This filter works great when doing Route::resources - to prove it, we use it for this package! Let's use the example of:

Route::group(array('before' => 'auth|magicaurp', 'prefix' => $baseurl), function () {
    Route::resource('permissions', 'Sorora\\Aurp\\Controllers\\PermissionsController');
});

As you can see, we have two filters. Auth simply checks if they are logged in, and if not they are sent to the login page. magicaurp checks the route they are accessing and then works out if they have permission to access it. It is important that permissions in the database follow a certain structure when being used for this filter.

• Creation of an item should have the permission task of "create_items" (Matches a resource controllers methods: create, store)
• Viewing (Single and Multiple) of an item should have the permission task of "show_items" (Matches a resource controllers methods: index, show)
• Editing/Modification of an item should have the permission task of "edit_items" (Matches a resource controllers methods: edit, update)
• Destruction of an item should have the permission task of "destroy_items" (Matches a resource controllers methods: destroy)

So, for our "permissions" example of magicaurp, the permissions to access each bit would be: create_permissions, show_permissions, edit_permissions and destroy_permissions

When a user does not have the permissions to get past the filter, a 403 is thrown. It is highly recommended you customise this page.

Example of 403 customisation:

App::error(function ($exception, $code) {
    if($code == 403)
    {
        return 'Sorry, you cannot access this area!';
    }
});

For a more detailed post on error customisation, see this blog post and comments.*

Important note

If for some reason you run the tests for this package, please note it refreshes all migrations and re-migrates the packages migrations to the database - so be warned, data may be lost!