Preface

Introduction

A framework agnostic permissions package that allows you to register permissions in a OOP way in your application.

The package requires PHP 8.0+ and comes bundled with a Laravel Service Provider to simplify the optional framework integration and follows the FIG standard PSR-4 to ensure a high level of interoperability between shared PHP code and is fully unit-tested.

Have a read through the Installation Guide.

Features

• Create Permissions Containers.
• Assign Groups to a Container.
• Assign Permissions to a Group.
• Assign a single Controller and a single or multiple methods to a Permission.
• Retrieve all the Groups from a Container.
• Retrieve all the Permissions from a Group.
• Check if a Container has any Groups.
• Check if a Group has any Permissions.

Examples

In this example we'll be covering all the 3 sections of the Permissions package, you can read about them on their appropriate sections.

use Cartalyst\Permissions\Container;

$container = new Container('main', function ($container) {
    // Assign some attributes
    $container->name = 'Main';
    $container->description = 'Main Container description.';

    // Create a new Group
    $container->group('main-group', function ($group) {
        // Assign some attributes
        $group->name = 'Main Group';
        $group->description = 'Main Group description.';

        // Create a new Permission
        $group->permission('foo', function ($permission) {
            $permission->name = 'Foo Permission';

            // Pass the controller methods as an array
            $permission->controller('App\Controllers\Foo', [ 'bar', 'baz' ]);
        });

        // Create a new Permission
        $group->permission('base', function ($permission) {
            $permission->name = 'Base Permission';

            // Pass the controller methods as a string
            $permission->controller('App\Controllers\Base', 'index, view, update');
        });
    });

    // Create another Group
    $container->group('other-group', function ($group) {
        // Assign some attributes
        $group->name = 'Another Group';
        $group->description = 'Another Group description.';
    });
});

Setup

Installation

The best and easiest way to install the Permissions package is with Composer.

Preparation

Open your composer.json file and add the following to the require array:

"cartalyst/permissions": "^3.0"

Add the following lines after the require array on your composer.json file:

"repositories": [
    {
        "type": "composer",
        "url": "https://packages.cartalyst.com"
    }
]

Note: Make sure that after the required changes your composer.json file is valid by running composer validate.

Install the dependencies

Run Composer to install or update the new requirement.

php composer install

or

php composer update

Now you are able to require the vendor/autoload.php file to autoload the package.

Integration

Cartalyst packages are framework agnostic and as such can be integrated easily natively or with your favorite framework.

Native

You'll only need to have a single or multiple Containers, if your application requires it, other than that you just need follow the Usage section :)

Laravel

The Permissions package has optional support for Laravel and it comes bundled with a Service Provider for easy integration.

After installing the package, open your Laravel config file located at app/config/app.php and add the following lines.

In the $providers array add the following service provider for this package.

'Cartalyst\Permissions\Laravel\PermissionsServiceProvider',

Now anywhere on your application call app('cartalyst.permissions') to have access to the main Permissions Container.

Usage

The usage of the Permissions package is very straight forward.

Note: This package doesn't come with any views, management, or real authentication/authorization functionality, this package aim is to provide a concise way to store your application permissions!

Briefing

Here we'll explain the 3 aspects of the Permissions package.

Container

The Container is the most important aspect of the Permissions package.

It needs to be the first thing you'll instantiate and it will be responsible for holding all of your permissions Groups and the corresponding permissions.

Group

The Group is the second thing to be instantiated and it's responsible for holding the permissions itself.

Permission

The Permission is the last thing to be instantiated and it can either hold the controller and the corresponding controller methods to be protected or just some minor attributes.

Container

The first step is to initialize a new Container.

Here's how you do it:

Parameters

Key	Required	Type	Default	Description
$id	true	string	void	The Container identifier.
$callback	false	Closure	null	A Closure used to assign attributes and/or to set a new Group.

Usage

use Cartalyst\Permissions\Container;

$container = new Container('main');
$container->name = 'Main';
$container->description = 'Main Container description.';

use Cartalyst\Permissions\Container;

$container = new Container('main', function ($container) {
    $container->name = 'Main';
    $container->description = 'Main Container description.';
});

Assign Groups

Assigning Groups to a Container is very straightforward and there's two ways of achieving the same goal.

Method 1

use Cartalyst\Permissions\Container;

$container = new Container('main', function ($container) {
    $container->name = 'Main';
    $container->description = 'Main Container description.';

    $container->group('main-group', function ($group) {
        $group->name = 'Main Group';
        $group->description = 'Main Container Group';
    });
});

Method 2

Please refer to the Group section and follow the instructions.

Check if the Container has groups

if ($container->hasGroups()) {
    echo 'Container has groups';
} else {
    echo 'Container has no groups.';
}

Get all groups

$groups = $container->all();

Get a specific group

$group = $container->find('foo');

Group

Now that we have a Container, we need to create a group, or multiple groups which will hold our permissions.

Here's how you do it:

Parameters

Key	Required	Type	Default	Description
$id	true	string	void	The Group identifier.
$callback	false	Closure	null	A Closure used to assign attributes and/or to set a new Permission.

Usage

$group = $container->group('main-group');
$group->name = 'Main Group';
$group->description = 'Main Container Group';

$group = $container->group('main-group', function ($group) {
    $group->name = 'Main Group';
    $group->description = 'Main Container Group';
});

Assign Permissions

Assigning Permissions to a Group is very straightforward and there's two ways of achieving the same goal.

Method 1

$group = $container->group('main-group', function ($group) {
    $group->name = 'Main Group';
    $group->description = 'Main Container Group';

    $group->permission('main', function ($permission) {
        $permission->name = 'Main';
        $permission->description = 'My Foo@bar Controller Permission';

        $permission->controller('App\Controllers\Foo', [ 'bar', 'baz' ]);
    });
});

Method 2

Please refer to the Permission section and follow the instructions.

Check if the Group has permissions

if ($group->hasPermissions()) {
    echo 'Group has permissions';
} else {
    echo 'Group has no permissions.';
}

Get all permissions

$permissions = $group->all();

Get a specific permission

$permission = $group->find('foo');

Permission

The Permission is the final step and works the same way as the Container and Group.

Here's how you do it:

Parameters

Key	Required	Type	Default	Description
$id	true	string	void	The Permission identifier.
$callback	false	Closure	null	A Closure used to assign attributes.

Usage

$permission = $group->permission('main');
$permission->name = 'Main';
$permission->description = 'My Main Permission';

$permission = $group->permission('main', function ($permission) {
    $permission->name = 'Main';
    $permission->description = 'My Main Permission';
});

Define a Permission for a Controller

If you want to protect a controller, you can use the controller() method when defining the permission.

Here's how you do it:

Parameters

Key	Required	Type	Default	Description
$name	true	string	void	The Permission identifier.
$methods	false	string | array	null	The methods of this controller.

Usage

// Pass the controller methods as an array
$permission->controller('App\Controllers\Foo', [ 'bar', 'baz' ]);

// Pass the controller methods as a string
$permission->controller('App\Controllers\Foo', 'bar, baz');

$permission = $group->permission('main', function ($permission) {
    $permission->name = 'Main';
    $permission->description = 'My Foo Controller Permission';

    // Protect the given controller and the given methods
    $permission->controller('App\Controllers\Foo', [ 'bar', 'baz' ]);
});