<commit_before># Entrust (Laravel4 Package)

Entrust is a succinct and flexible way to add Role-based Permissions to **Laravel4**.

First and foremost I must give credit to the original developers of this package.
<NAME> (@andrewelkins) and <NAME> (@zizaco) did excellent work on the fundamental design and functionality.
My fork is intended to:
- Remove extra components not really relevant to role & permission management (in particular, Ardent).
- Add extra functionality I felt was useful and particularly suited to this package.
- Make integrating the package more flexible and dynamic (eventually).

Were my changes ever to be integrated back into the Zizaco version of this plugin, I think that would be lovely.
Either way though, I hope to demonstrate some genuinely helpful features and options.

## Contents

- [Quick start](#quick-start)
    - [Required setup](#required-setup)
- [Configuration](#configuration)
    - [User relation to roles](#user-relation-to-roles)
    - [Models](#models)
        - [Role](#role)
        - [Permission](#permission)
        - [User](#user)
- [Usage](#usage)
    - [Concepts](#concepts)
        - [Checking for Roles & Permissions](#checking-for-roles--permissions)
        - [User ability](#user-ability)
    - [Short syntax route filter](#short-syntax-route-filter)
    - [Route filter](#route-filter)
- [Troubleshooting](#troubleshooting)
- [License](#license)
- [Additional information](#additional-information)

## Quick start

**PS:** Even though it's not needed, Entrust works very well with [Confide](https://github.com/Zizaco/confide) in order to eliminate repetitive tasks involving the management of users: account creation, login, logout, confirmation by e-mail, password reset, etc.

[Take a look at Confide](https://github.com/Zizaco/confide).

### Required setup

In the `require` key of `composer.json` file add the following:

```json
"bbatsche/entrust": "~2.0"
```

Run the Composer update command:

```bash
composer update
```

In your `config/app.php` add `'Bbatsche\Entrust\EntrustServiceProvider'` to the end of the `$providers` array:

```php
'providers' => array(
    'Illuminate\Foundation\Providers\ArtisanServiceProvider',
    'Illuminate\Auth\AuthServiceProvider',
    ...
    'Bbatsche\Entrust\EntrustServiceProvider',
),
```

At the end of `config/app.php` add `'Entrust' => 'Bbatsche\Entrust\EntrustFacade'` to the `$aliases` array:

```php
'aliases' => array(
    'App'        => 'Illuminate\Support\Facades\App',
    'Artisan'    => 'Illuminate\Support\Facades\Artisan',
    ...
    'Entrust'    => 'Bbatsche\Entrust\EntrustFacade',
),
```

## Configuration

Set the property values in the `config/auth.php`.
These values will be used by entrust to refer to the correct user table and model.

You can also publish the configuration for this package to further customize table names and model namespaces:

```bash
php artisan config:publish bbatsche/entrust
```

### User relation to roles

Now generate the Entrust migration:

```bash
php artisan entrust:migration
```

It will generate the `<timestamp>_entrust_setup_tables.php` migration.
You may now run it with the artisan migrate command:

```bash
php artisan migrate
```

After the migration, four new tables will be present:
- `roles` which stores roles.
- `permissions` for storing permissions
- `role_user` & `permission_role` which will represent the [Many-to-Many](http://laravel.com/docs/4.2/eloquent#many-to-many) relationship between `User`, `Role`, and `Permission`.

### Models

#### Role

Create a Role model inside `app/models/Role.php` using the following example:

```php
<?php

use Bbatsche\Entrust\EntrustRole;

class Role extends EntrustRole
{
}
```

The `Role` model has three main attributes:
- `name`: the name of the Role, the unique key used to represent the Role in your application. For example: "admin", "owner", "employee".
- `display_name`: the human readable name for that role, it is not unique and may be used for display purposes. For example: "User Administrator", "Project Owner", "Widget  Co. Employee".
- `description`: a longer form description of the role.

Both `display_name` and `description` are optional; their fields are nullable in the database.

#### Permission

Create a Permission model inside `app/models/Permission.php` using the following example:

```php
<?php

use Bbatsche\Entrust\EntrustPermission;

class Permission extends EntrustPermission
{
}
```

The `Permission` model has the same three attributes as the `Role`:
- `name`: the name of the Permission, the unique key used to represent the Permission in your application. For example: "create-post", "edit-user", "post-payment", "mailing-list-subscribe".
- `display_name`: the viewer friendly version of the permission string. For example "Create Posts", "Edit Users", "Post Payments", "Subscribe to mailing list".
- `description` Description can be a more detailed explanation for the Permission. In general, it may be helpful to think of the attributes in the form of a sentence: "The permission `display_name` allows a user to `description`."

These three fields have the same general purpose as for your Roles, but instead applied to the Permission model.

#### User

Next, use the `HasRole` trait in your existing `User` model. For example:

```php
<?php

use Bbatsche\Entrust\HasRole;

class User extends Eloquent
{
    use HasRole; // add this trait to your user model

    ...
}
```

This will enable the relation with `Role` and add the following methods `roles()`, `hasRole($name)`, `can($permission)`, and `ability($roles, $permissions, $options)` within your `User` model.

Don't forget to dump composer autoload

```bash
composer dump-autoload
```

**And you are ready to go.**

## Usage

### Concepts
Let's start by creating the following `Role`s and `Permission`s:

```php
$owner = new Role();
$owner->name         = 'owner';
$owner->display_name = 'Project Owner'; // optional
$owner->description  = 'User is the owner of a given project'; // optional
$owner->save();

$admin = new Role();
$admin->name         = 'admin';
$admin->display_name = 'User Administrator'; // optional
$admin->description  = 'User is allowed to manage and edit other users'; // optional
$admin->save();
```

Next, with both roles created let's assign them to the users.
Thanks to the `HasRole` trait this is as easy as:

```php
$user = User::where('username', '=', 'bbatsche')->first();

// role attach alias
$user->attachRole($admin); // parameter can be an Role object, array, or id<commit_msg>Add information about soft deleting to README<commit_after># Entrust (Laravel4 Package)

Entrust is a succinct and flexible way to add Role-based Permissions to **Laravel4**.

First and foremost I must give credit to the original developers of this package.
<NAME> (@andrewelkins) and <NAME> (@zizaco) did excellent work on the fundamental design and functionality.
My fork is intended to:
- Remove extra components not really relevant to role & permission management (in particular, Ardent).
- Add extra functionality I felt was useful and particularly suited to this package.
- Make integrating the package more flexible and dynamic (eventually).

Were my changes ever to be integrated back into the Zizaco version of this plugin, I think that would be lovely.
Either way though, I hope to demonstrate some genuinely helpful features and options.

## Contents

- [Quick start](#quick-start)
    - [Required setup](#required-setup)
- [Configuration](#configuration)
    - [User relation to roles](#user-relation-to-roles)
    - [Models](#models)
        - [Role](#role)
        - [Permission](#permission)
        - [User](#user)
        - [Soft Deleting](#soft-deleting)
- [Usage](#usage)
    - [Concepts](#concepts)
        - [Checking for Roles & Permissions](#checking-for-roles--permissions)
        - [User ability](#user-ability)
    - [Short syntax route filter](#short-syntax-route-filter)
    - [Route filter](#route-filter)
- [Troubleshooting](#troubleshooting)
- [License](#license)
- [Additional information](#additional-information)

## Quick start

**PS:** Even though it's not needed, Entrust works very well with [Confide](https://github.com/Zizaco/confide) in order to eliminate repetitive tasks involving the management of users: account creation, login, logout, confirmation by e-mail, password reset, etc.

[Take a look at Confide](https://github.com/Zizaco/confide).

### Required setup

In the `require` key of `composer.json` file add the following:

```json
"bbatsche/entrust": "~2.0"
```

Run the Composer update command:

```bash
composer update
```

In your `config/app.php` add `'Bbatsche\Entrust\EntrustServiceProvider'` to the end of the `$providers` array:

```php
'providers' => array(
    'Illuminate\Foundation\Providers\ArtisanServiceProvider',
    'Illuminate\Auth\AuthServiceProvider',
    ...
    'Bbatsche\Entrust\EntrustServiceProvider',
),
```

At the end of `config/app.php` add `'Entrust' => 'Bbatsche\Entrust\EntrustFacade'` to the `$aliases` array:

```php
'aliases' => array(
    'App'        => 'Illuminate\Support\Facades\App',
    'Artisan'    => 'Illuminate\Support\Facades\Artisan',
    ...
    'Entrust'    => 'Bbatsche\Entrust\EntrustFacade',
),
```

## Configuration

Set the property values in the `config/auth.php`.
These values will be used by entrust to refer to the correct user table and model.

You can also publish the configuration for this package to further customize table names and model namespaces:

```bash
php artisan config:publish bbatsche/entrust
```

### User relation to roles

Now generate the Entrust migration:

```bash
php artisan entrust:migration
```

It will generate the `<timestamp>_entrust_setup_tables.php` migration.
You may now run it with the artisan migrate command:

```bash
php artisan migrate
```

After the migration, four new tables will be present:
- `roles` which stores roles.
- `permissions` for storing permissions
- `role_user` & `permission_role` which will represent the [Many-to-Many](http://laravel.com/docs/4.2/eloquent#many-to-many) relationship between `User`, `Role`, and `Permission`.

### Models

#### Role

Create a Role model inside `app/models/Role.php` using the following example:

```php
<?php

use Bbatsche\Entrust\EntrustRole;

class Role extends EntrustRole
{
}
```

The `Role` model has three main attributes:
- `name`: the name of the Role, the unique key used to represent the Role in your application. For example: "admin", "owner", "employee".
- `display_name`: the human readable name for that role, it is not unique and may be used for display purposes. For example: "User Administrator", "Project Owner", "Widget  Co. Employee".
- `description`: a longer form description of the role.

Both `display_name` and `description` are optional; their fields are nullable in the database.

#### Permission

Create a Permission model inside `app/models/Permission.php` using the following example:

```php
<?php

use Bbatsche\Entrust\EntrustPermission;

class Permission extends EntrustPermission
{
}
```

The `Permission` model has the same three attributes as the `Role`:
- `name`: the name of the Permission, the unique key used to represent the Permission in your application. For example: "create-post", "edit-user", "post-payment", "mailing-list-subscribe".
- `display_name`: the viewer friendly version of the permission string. For example "Create Posts", "Edit Users", "Post Payments", "Subscribe to mailing list".
- `description` Description can be a more detailed explanation for the Permission. In general, it may be helpful to think of the attributes in the form of a sentence: "The permission `display_name` allows a user to `description`."

These three fields have the same general purpose as for your Roles, but instead applied to the Permission model.

#### User

Next, use the `HasRole` trait in your existing `User` model. For example:

```php
<?php

use Bbatsche\Entrust\HasRole;

class User extends Eloquent
{
    use HasRole; // add this trait to your user model

    ...
}
```

This will enable the relation with `Role` and add the following methods `roles()`, `hasRole($name)`, `can($permission)`, and `ability($roles, $permissions, $options)` within your `User` model.

Don't forget to dump composer autoload

```bash
composer dump-autoload
```

**And you are ready to go.**

#### Soft Deleting

The default migration takes advantage of `onDelete('cascade')` clauses within the pivot tables to remove relations when a parent record is deleted. If for some reason you cannot use cascading deletes in your database, the EntrustRole and EntrustPermission classes, and the HasRole trait include event listeners to manually delete records in relevant pivot tables. In the interest of not accidentally deleting data, the event listeners will **not** delete pivot data if the model uses soft deleting. However, due to limitations in Laravel's event listeners, there is no way to distinguish between a call to `delete()` versus a call to `forceDelete()`. For this reason, **before you force delete a model, you must manually delete any of the relationship data** (unless your pivot tables uses cascading deletes). For example:

```php
$role = Role::findOrFail(1); // Pull back a given role

// Regular Delete
$role->delete(); // This will work no matter what

// Force Delete
$role->users()->sync([]); // Delete relationship data
$role->perms()->sync([]); // Delete relationship data

$role->forceDelete(); // Now force delete will work regardless of whether the pivot table has cascading delete
```

## Usage

### Concepts
Let's start by creating the following `Role`s and `Permission`s:

```php
$owner = new Role();
$owner->name         = 'owner';
$owner->display_name = 'Project Owner'; // optional
$owner->description  = 'User is the owner of a given project'; // optional
$owner->save();

$admin = new Role();
$admin->name         = 'admin';
$admin->display_name = 'User Administrator'; // optional
$admin->description  = 'User is allowed to manage and edit other users'; // optional
$admin->save();
```

Next, with both roles created let's assign them to the users.
Thanks to the `HasRole` trait this is as easy as:

```php
$user = User::where('username', '=', 'bbatsche')->first();

// role attach alias
$user->attachRole($admin); // parameter can be an Role object, array, or id
{'fraction_non_alphanumeric': 0.11673747997492512, 'fraction_numerical': 0.0009054816465835481, 'mean_word_length': 4.407909604519774, 'pattern_counts': {'":': 2, '<': 15, '<?xml version=': 0, '>': 47, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3644767', 'n_tokens_mistral': 4243, 'n_tokens_neox': 3976, 'n_words': 1674}