Download the PHP package foss-haas/laravel-permission-objects without Composer

Laravel Permission Objects

This package implements object-level, model-level and simple permissions for Laravel.

Once installed you can do stuff like this:

Basic Usage

Modify User Model

If you want to add permissions to your users, you will need to add an attribute to store the permissions. You can call it anything you want:

You need to cast it to AsPermissions or AsScopedPermissions depending on whether you need permissions to be global or scoped (e.g. to a tenant):

Define Permissions

You can define permissions in your service provider's boot method:

By default permission names will be qualified with the full name of the model class they're defined for. If you want nicer looking (shorter) names, you can use morph maps. Make sure to define your morph maps before looking up permissions:

You can also define permissions for classes that are not models:

Look Up Definitions

You can look up permissions you have defined using the short name and the name of the class they were defined for:

You can also look them up using the fully qualified name:

Using Models

If you want to look up permission objects from the models you define them for, you can also add the HasPermissions trait to them:

Now you can look up permissions defined for your model on the model:

The Permission class comes with this trait already baked in so there is no need to extend it if you want to define permissions for it:

Assign permissions

You can use the methods on your model's permissions attribute to manage its assigned permissions. You can either pass the key (or ID) of the instance (object) you want the permission to be restricted to or null if you want the permission to be valid for any instance of its type.

When passing an ID make sure it is cast to a string if it isn't one already:

Granting a model level permission (using null) will override any existing object level permissions (using object IDs) of the same permission type.

Revoking a model level permission has no effect if the user was only granted object level permissions. In this case revokeAll can be used to revoke any model or object level permissions of the permission type:

Check permissions

The permissions attribute supports a simple presence check:

If a permission was granted at the model level (using null), any instance level checks will also pass:

Using Gates

The permissions attribute also provides a can method which can be used in a Gate::after fallback in your service provider if you don't want to set up gates or policies yourself:

This also works when using AsScopedPermissions:

Note that the can method returns null when passed a permission name it does not recognize or that can't be resolved using the object or object type it is passed.

Simple Permissions

Permissions don't have to be tied to specific models or classes. You can define simple permissions by passing null instead of a class when registering them:

Note that you will still need to pass null as an object ID when using this permission as this argument is intentionally not optional to avoid mistakes:

If you want to misuse the object ID for your own purposes, keep in mind that the can method will not work correctly as it expects the string argument to be a class name and will attempt to resolve the permission name using it:

Super Admins

Although not built for this purpose, simple permissions can be used to implement a "super admin" flag that will pass all Gate or Policy checks:

Scoped Permissions

When using AsScopedPermissions, you can pass in an additional scopes parameter to method calls to define which scope or scopes the method should consider:

Alternatively, you can use the scope method to access the AsPermissions for that scope directly:

Scopes are identified by their name as string values. The meaning of scopes is up to your application's needs but could range from organizational units of your company to different customers in a poor man's single-database multi-tenancy implementation.

The default or global scope is identified by AsScopedPermissions::DEFAULT_SCOPE (which is set to the empty string) and will be used if no scope is passed explicitly.

All permission checks using has or can will always also check the default scope in addition to any scopes passed explicitly.

You can also use AsScopedPermissions::ALL_SCOPES (which is set to '*') to refer to all scopes, e.g. to revoke a given permission across all scopes:

Roles

If you want to implement role-based authorization, you can create a role model and give it an AsPermissions attribute just as you would for a user model. As this package aims to be unopinionated, how you use this model is up to you, but a possible schema could look like this:

License

Copyright (c) 2004 Foss & Haas GmbH.

This package is licensed under the terms of the MIT license.