Download the PHP package michaeltintiuc/laravel-permy without Composer
On this page you can find all versions of the php package michaeltintiuc/laravel-permy. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download michaeltintiuc/laravel-permy
More information about michaeltintiuc/laravel-permy
Files in michaeltintiuc/laravel-permy
Package laravel-permy
Short Description Laravel user permissions (roles or groups) based on defined routes.
License MIT
Informations about the package laravel-permy
Laravel Permy
Short for "permanent friend" - My Mom said it's pretty cool!
A powerful and flexible ACL for all your Laravel applications; supporting version of 4.2 and higher
- Assign single or multiple permissions to users and control the inheritance logic via
AND
,OR
orXOR
operators - Use multiple User Models
- Manage permissions from the UI or DB with localization support
- Set your permissions directly on Routes, Route Groups or Controllers via filters/middleware
- Batch permission checking with extra logical operators
- Artisan commands and Debugging helpers
TODO
- [ ] Class refactoring and abstraction
- [ ] Add operator key support for array permissions to artisan command
- [ ] Additional helper artisan commands
- [ ] Add PHP7 typing
- [ ] Improve DB access, minimize amount of queries
- [ ] Add Blade directives
Contents
The only section without hilarious comments
- Installation
- Publishing
- Database
- Usage
- Configuration
- Localization
- Artisan Commands
- Exceptions
- Feedback
Installation
The beginning of a beautiful friendship (with cheesy music in the background)
Require via composer
For Laravel 5.5+ you do not need to manually add the Service Provider nor the Facade (alias) - these will be auto-discovered
Append the Service Provider to your providers array in app/config/app.php
(4.2) or config/app.php
(5.0+)
Append the Facade to your facades array in app/config/app.php
(4.2) or config/app.php
(5.0+)
Add the Trait to your User Models or any other Models you need permissions for.
Publishing
I can't publish this anymore...
Migrations
Laravel 4.2
Laravel 5.0+
Configs
This is an optional step, the description of the configuration file will follow below
Laravel 4.2
Laravel 5.0+
Translations
This is an optional step, the configuration of the language file will follow below
Laravel 4.2
Create file app/lang/packages/en/laravel-permy/defaults.php
You may create this file for each locale used by your app simply by substituting en
to fr
(for example)
Laravel 5.0+
Database
Drop the base, wait! No, that's not what I meant!
After you've successfully published the migration files, you should have 2 files:
create_permy_table
and create_permy_user_table
The permy
table is responsible for storing all of your future permissions
while the permy_user
table holds the relation of users to their respective permissions
Permy works in a way that each permission has a name, description and whole lot of columns, each representing a controller that has restricted user access. Now onto configuring it.
Leave the boilerplate as is
Create a column for every controller that needs access restriction.
We're specifying controllers which will use the Permy middleware/filters.
These should be fully name-spaced class names and \ (backslashes)
replaced with :: double colons
like so:
Original Controller class name:
Resulting php and column name:
The column type is text
because we'll be storing JSON data that will represent access to specific Controller methods. We also set the column to be nullable
because well... you might forget that you've created several new Controllers and/or methods for your awesome feature, this will allow a graceful fallback of either restricting or allowing access (we'll discuss this in-depth a bit later).
Now that you're all set - update your database
Usage
I know, finally... but it's well worth it, I promise!
Middleware/Filters
Laravel 4.2
Add the filter to the end of your app/filters.php
file
Laravel 5.0+
Add the middleware to the $routeMiddleware
array in your app/Http/Kernel.php
file
This is a base filter/middleware and will simply spit our 403 - Forbidden
on restricted routes. If you'd like to display custom text, view or perhaps a redirect you can provide your own class.
All you have to do is perform a check using Permy::can($route)
in your implementation.
Have a look at the source code of the filter or middleware and the Laravel docs 4.2, 5.0+ on how to implement custom filters.
Routes & Controllers
Laravel 4.2
These must be before filters
Applied directly to a route
Or to a route group
Or within a controller
Laravel 5.0+
Applied directly to a route
Or to a route group
Or within a controller
At this point you're done and can test the application.
If you've assigned the filter/middleware to Acme\SomeController
which has index
and someMethod
methods you can insert a new row in the permy
table with a test JSON for the Acme::SomeController
column:
Note the ID of the new row and insert a new one in the permy_user
table binding the permission ID to an existing user.
This will now allow the assigned user to issue requests to the index
method and prevent access to someMethod
.
If you try the above routes with a different user, all requests will be blocked, in fact any requests to methods which were not explicitly set will also be blocked. This behavior can be overridden through the config file.
Methods
can
Allows you to check if the current user can access one or multiple routes or controller methods. You can mix route names, controller class names/methods and Route objects when passing an array.
Basic
Advanced
You can perform additional logic operations on the resulting permissions.
cant
Same as can(), this is a helper function.
getList
Runs a check against all routes and controllers that have a fillable filter/middleware assigned to them. Builds a localized array of controller/method names and descriptions. Creates/updates the translation file.
Useful when fetching permissions data for UI management.
setUser
Provide a specific user instead of the default authenticated one
getUser
Helper function for testing/debugging
setDebug
Overrides the config value for current call (see Config docs for details)
setGodmode
All checks return true. Why not, right? (see Config docs for details)
setRolesLogicOperator
Overrides the config value for current call (see Config docs for details)
Configuration
What there's more?!
logic_operator
If multiple permissions are assigned to a user and there are conflicting permissions per route/method, which logical operator to use? Invalid values default to and
Default: and
Allowed values & behavior:
and
- All permissions must be trueor
- At least one of the permissions must be truexor
- Exclusive or
users_model
Sets the default User model used in CLI artisan command and PermyModel describing the many-to-many relationship.
Default: App\User
godmode
When set to true, all route permissions return true. Useful for debugging, I guess...
Default: false
debug
When set to true, all exceptions during permission checking will be thrown. Consider it strict mode
Default: false
filters
An array of filters based on which Permy builds a list of permissions to manage. The fillable array represents the filters that are manageable through the UI. The guarded array represents the filters that are not seen in the UI and are managed manually through the DB or CLI.
Default:
Localization
OMG PLZ STAHP!
After calling the getList()
method, you now have language files for all of your restricted routes and controllers.
You are encouraged to edit these files in order to provide a better understanding to those who manage the application on the front-end.
File Location:
Laravel 4.2
app/lang/packages/{locale}/laravel-permy/permy.php
Laravel 5.0+
resources/lang/vendor/laravel-permy/{locale}/permy.php
Example file:
If you've published the translation files, as mentioned at the very top, you should have the defaults.php
file in your app's lang directory.
It's responsible for the default (duh!) names and descriptions of controllers and methods.
When the permy.php
file is created for the first time or updated with new data - these are the values that everybody dislikes to update so much.
You can have translations of this file for each locale.
Artisan Commands
HALT AND CATCH FIRE
can
Mimics the Permy
public methods, only cooler cause it's from CLI.
Prints the result back on screen in pretty colors.
More commands coming soon
Exceptions
RTFM - Achievement Unlocked!
If debug
or strict mode
(if you will) is set to true these Exceptions may be thrown.
You are more than welcome to catch them anywhere in your app.
PermyFileCreateException
Error creating the permy.php
language file
PermyFileUpdateException
Error updating the permy.php
language file
PermyMethodNotSetException
The method you're trying to check is not explicitly set in the DB. Defaults to false when debug is false
PermyControllerNotSetException
The controller you're trying to check does not exist the DB as a column name. Defaults to false when debug is false
PermyPermissionsNotFoundException
Failed to get permissions for current user
Feedback
The back needs proper feeding and you're not doing anything about it!
Collaboration, bug-reports, feature and pull requests are always welcome!