An open API service indexing awesome lists of open source software.

https://github.com/eloyekunle/permissionsbundle

A Flexible Permission Management module for Symfony
https://github.com/eloyekunle/permissionsbundle

bundle php roles-management symfony symfony-bundle user-management

Last synced: 3 months ago
JSON representation

A Flexible Permission Management module for Symfony

Awesome Lists containing this project

README

        

EloyekunlePermissionsBundle
===========================

[![Build Status](https://travis-ci.org/eloyekunle/PermissionsBundle.svg?branch=master)](https://travis-ci.org/eloyekunle/PermissionsBundle)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/eloyekunle/PermissionsBundle/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/eloyekunle/PermissionsBundle/?branch=master)
[![Code Coverage](https://scrutinizer-ci.com/g/eloyekunle/PermissionsBundle/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/eloyekunle/PermissionsBundle/?branch=master)

The EloyekunlePermissionsBundle provides support for a database-backed permissions system in Symfony2.
It provides a flexible framework for permissions management that aims to handle common tasks such as flexible
Permissions Definitions, Roles Creation and Authorization Checking (using Symfony Voters).

Features include:

- Roles can be stored via Doctrine ORM.
- Flexible & Modular permissions definitions in YAML files. From few permissions to hundreds, this bundle has your back.
- Symfony Voter for Authorization Checking.
- Unit tested.

CONTENTS
--------

* [Installation](#installation)
* [Usage](#usage)
* [Contributions](#contributions)
* [Support](#support)
* [Credits](#credits)

## INSTALLATION
Installation is a quick (I promise!) 5 step process:

1. [Download EloyekunlePermissionsBundle using composer](#step-1-download-the-bundle)
2. [Enable the Bundle](#step-2-enable-the-bundle)
3. [Create your Role class](#step-3-create-role-class)
4. [Configure your User class](#step-4-configure-your-user-class)
5. [Configure the bundle](#step-5-configure-the-bundle)
6. [Update your database schema](#step-5-update-your-database-schema)

### Step 1: Download the bundle

Open a command console, enter your project directory and execute the
following command to download the latest stable version of this bundle:

```bash
$ composer require "eloyekunle/permissions-bundle"
```

This command requires you to have Composer installed globally, as explained
in the [installation chapter](https://getcomposer.org/doc/00-intro.md) of the Composer documentation.

### Step 2: Enable the bundle

Then, enable the bundle by adding the following line in the ``config/bundles.php``
file of your project, e.g. (Symfony >=4):

```php
// config/bundles.php
return [
// ...
Eloyekunle\PermissionsBundle\EloyekunlePermissionsBundle::class => ['all' => true],
];
```

### Step 3: Create Role class

The goal of this bundle is to persist some ``Role`` class to a database.
Your first job, then, is to create the ``Role`` class
for your application. This class can look and act however you want: add any
properties or methods you find useful. This is *your* ``Role`` class.

The bundle provides base classes which are already mapped for most fields
to make it easier to create your entity. Here is how you use it:

1. Extend the base ``Role`` class (from the ``Model`` folder if you are using
any of the doctrine variants)
2. Map the ``id`` field. It must be protected as it is inherited from the parent class.
3. When you extend from the mapped superclass provided by the bundle, don't
redefine the mapping for the other fields as it is provided by the bundle.
4. If you override the __construct() method in your Role class, be sure
to call parent::__construct(), as the base Role class depends on this to initialize some fields.

#### Doctrine ORM Role class

If you're persisting your roles via the Doctrine ORM, then your ``Role`` class
should live in the ``Entity`` namespace of your bundle and look like this to
start:

##### PHP

```php

* array (
* 'title' => 'Edit Content',
* 'description' => 'Grants permission to edit content.',
* 'dependencies' =>
* array (
* 0 => 'view content',
* ),
* 'provider' => 'content',
* ),
* 'view content' =>
* array (
* 'title' => 'View Content',
* 'description' => 'Grants permission to view content.',
* 'provider' => 'content',
* ),
* )
*/
$permissions = $permissionsHandler->getPermissions();
// ........................
}
}
```

### 2. Set up a Role

The bundle ships with a [`RoleManager`](https://github.com/eloyekunle/PermissionsBundle/blob/master/Model/RoleManagerInterface.php)
which is available as a service and can be injected into your Controllers/Services. It contains useful utility methods
to manager roles. You can also `get` it from the container as `eloyekunle_permissions.role_manager`.

```php
createRole();
$role->setRole('Content Admin');

$roleManager->updateRole($role);
// ......
}
}
```

This creates and persists a `Role` entity to your database.

### 3. Check Permissions in your Controllers

The bundle ships with a [voter](https://symfony.com/doc/current/security/voters.html), [`PermissionsVoter`](https://github.com/eloyekunle/PermissionsBundle/blob/master/Security/PermissionsVoter.php).
You can check for user permissions by using the `isGranted()` method on Symfony's authorization checker or call
`denyAccessUnlessGranted()` in a controller.

```php
denyAccessUnlessGranted('edit content');
// Get a Content object - e.g. query for it.
// $content = ......;
}

/**
* @Route("/content/{id}", name="content_show")
*/
public function show($id)
{
$this->denyAccessUnlessGranted('view content');
// Get a Content object - e.g. query for it.
// $content = ......;
}
}
```

## CONTRIBUTIONS

Contributions of any kind are welcome: code, documentation, ideas etc.
Issues and feature requests are tracked in the [Github issue tracker](https://github.com/eloyekunle/PermissionsBundle/issues).

## SUPPORT
If you need any support related to this bundle, you can contact me on the [Symfony Slack group](http://symfony-devs.slack.com)
(eloyekunle), or send me an email ([email protected]).

## CREDITS
- Bundle inspired by the [Drupal Permissions System](https://api.drupal.org/api/drupal/core!core.api.php/group/user_api/8.5.x)!
- Implementation inspired by some excellent Symfony bundles, especially [FOSUserBundle](https://github.com/FriendsOfSymfony/FOSUserBundle).
- [Elijah Oyekunle](https://elijahoyekunle.com) - [LinkedIn](https://www.linkedin.com/in/elijahoyekunle) - [Twitter](https://twitter.com/elijahoyekunle) - [Github](https://github.com/eloyekunle)