Download the PHP package sourcefli/laravel-permission-name-generator without Composer

Laravel Permission Name Generator

Intro

Create and Retrieve permission strings using methods instead of strings, and a very simple configuration.

Each item listed in the config will get a 'permission set', one of each:

• browse
• read
• edit
• add
• delete
• restore
• force_delete
• * (referenced using the 'wildcard' method)

Quick Example

Adding one item within the resources array in your config, such as...

Produces the following permission strings... Note: each item wrapped in brackets will be later referenced as a 'scope'

An example to access one of these permission strings in your Laravel app...

Examples to grab subsets of permissions for a resource:

Authorization Note:

All package logic is related to generating 'permission strings' very easily and retrieving them very easily throughout your app. Convention, predictability, and reduce boilerplate are at the heart of what I was going for.

Overview

Got pretty annoyed with always having to remember which permissions were plural, which syntax allowed the user to view 'team' permissions vs which permissions were just for the user's own resources. On top of that, having to hard code permission strings throughout the application, or create a wrapper each time. These seemed like such a common routines, I decided to venture out and create a package for this.

Installation

Publish Config

Detailed Usage

Add Resources/Settings To Config File

Note: See QA Section at bottom of this readme to see why brackets are used and a couple other questions you might have

Now Use It

This example might be the permission used when you want to know if:

The current user can edit the billing settings THEY OWN in the application

or

This example might be the permission used when you want to know if:

The current user can edit the billing settings THEIR TEAM OWNS, or ANYONE ON THEIR TEAM OWNS (just throwing out examples)

'Settings' Items

The settings section in the config file is optional. This is added in the case that you have settings related permissions that are seperate from your resources.

Now Use It

This example might be the permission used when you want to know if:

The current user can edit the smtp settings that THEY OWN...

This example might be the permission used when you want to know if:

The current user can edit the smtp settings THEIR TEAM OWNS

Any distinction between the 'team' scope and the 'owned' scope is open to interpretation as is needed for your app, of course. I'm just listing out some examples of how I've used these permission strings before.

Global Helpers

There are 4 global 'helper' functions available. They are:

Helper Function Arguments

Option A.

If you pass a resource or setting (whichever is relevant to the function you're calling) as an argument, all of these functions will return their respective adapter - which means you can chain any of the retrieval methods onto it just like the Facade behavior, like so:

Option B:

If no argument is passed to any of these methods, you will get a collection of all the permissions that are related to that 'scope':

ONLY and EXCEPT methods

As briefly shown above, when you're defining roles and which permissions are associated with them, you'll need to tell your app which permissions should be included/excluded from each set of 'resources' or 'settings' that you've defined in the config file. For this, you can use the only() method or the except() method. These methods accept a list of abilities as a comma-seperated string or an array.

For Example, if using the same configs as mentioned above:

!! Important Note !!

Be careful when using the except() method since the * permission is always present in the Collection that gets returned, and will remain present unless otherwise specified.

Similar to parsing requests within Laravel, it's safest to stick with the only() method to ensure you're cherry-picking the exact permissions you're looking for.

Since All Facades are aliased in the global namespace, using the Facades in your views wont create a mess either.

Retrieval 'all' Permissions

This example provides access to ALL permissions available ('resources' and 'settings' combined):

This example returns all 'resources' within the 'owned' scope:

(see below for further explanation on 'scope')

This package comes with 5 of these facades, each has their own 'scope' which I'll talk about further below.

You can also use the root aliases...

A Little More In Depth

'Permission Set' Definition:

In the config, any 'resource' or 'setting' will get it's own set of permissions... For example:

Adding those three items to your config would generate the following 'permission sets'

As you can see, each 'resource' listed in the config will generate one 'permission set' of [owned] permissions and one 'permission set' of [team] permissions.

And any 'setting' item listed in the config will generate one 'permission set' of [owned_setting] and one 'permission set' of [team_setting]

Each 'permission set' contains all 8 permissions:

• browse
• read
• edit
• add
• delete
• restore
• force_delete
• *

Calling On Permissions Throughout Your App:

Using the same config as mentioned in the 'Permission Set' definition, you can call methods using the same name on each related Facade.

**With the exception of the AllPermissions facade, which I'll get to in a bit.

For Example, we can now call these methods:

Retrieval Methods:

'Retreival Methods' are the methods that you can chain onto any of your resources or settings methods that you've already called on a Facade.

These include:

browse()

read()

edit()

add()

delete()

force_delete()

restore()

wildcard()

For Example:

for any of your 'resources', you can call

OwnedPermission::user()->create(); 

TeamPermission::billing()->edit();

...

or, for your 'settings'

OwnedSettingPermission::smtp()->read();

TeamSettingPermission::smtp()->delete();

...

The AllPermissions Facade

This facade works a little differently then the others, though it's just a small difference. If want to get a collection of ALL your permissions, you can call:

Getting Individual Permissions From The AllPermission Facade:

If you want to retrieve permission strings from this Facade, it's a little different from the others.

First, you have set a scope, then you can chain the standard methods as listed above (check out the tests starting here for sample usage).

There are 4 methods that set the scope for the AllPermissions Facade:

The 'all' Method On All Facades:

You can call the all() method on any of the Facades in order to:

A. Get a complete list of permissions that are within that scope, if no resource is set. (see example 'A' below)

B. Get a set resource/setting related permissions, if the resource/setting is set on that instance. (see example 'B' below)

owned, team, owned_setting, team_setting

For Example:

QA:

1. What are the brackets for on each permission string?

This is to prevent any naming clashes with the 'resources' and 'settings' that you have listed in your config file. If you're looking at the source code, these are often referred to as ownershipScopes or just scopes

2. Why Is Everything Singular?

This is intentional and provides a unified and predictable format across the board... The AllPermissions Facade is the only thing that's not singular.

3. Can I add my own scopes?

No, right now there's only 4 available. Each represented by a Facade, or their own global helper

• owned permissions
• team permissions
• owned setting permissions
• team setting permissions

4. Can Permissions be queried in any way?

Only if you've saved the permissions to your database, then you can use your ORM. This package is only intended to either return an \Illuminate\Support\Collection of permissions (either scoped, or all permissions, using the AllPermissions Facade). or to retrieve a single permission as a string. I plan to add the only() and except() methods (like Spatie's Data Transfer Object Package) but that's as fancy as the methods will get. I intend to keep this package as simple as possible.

Back To The Top

Back To The Top

Credits

• Spatie For doing all the hard work in their permissions package. I also make use of their once function to help with performance in this package.

Security

• Please let me know of any security related issues asap at [email protected].

License

MIT.

Please see the opensource.org site definition for more information.