Skip to content

Commit 3b77e98

Browse files
radiatecoderadiatecode
committed
read me updated
1 parent f6e9f90 commit 3b77e98

File tree

3 files changed

+147
-117
lines changed

3 files changed

+147
-117
lines changed

‎README.md‎

Lines changed: 143 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,8 @@
11
# Laravel Permission Name Generator
2-
[![Latest Version on Packagist](https://img.shields.io/packagist/v/radiatecode/laravel-route-permission.svg?style=flat-square)](https://packagist.org/packages/radiatecode/laravel-route-permission)
3-
[![Total Downloads](https://img.shields.io/packagist/dt/radiatecode/laravel-route-permission.svg?style=flat-square)](https://packagist.org/packages/radiatecode/laravel-route-permission)
2+
[![Latest Version on Packagist](https://img.shields.io/packagist/v/radiatecode/laravel-permission-name-generator.svg?style=flat-square)](https://packagist.org/packages/radiatecode/laravel-permission-name-generator)
3+
[![Total Downloads](https://img.shields.io/packagist/dt/radiatecode/laravel-permission-name-generator.svg?style=flat-square)](https://packagist.org/packages/radiatecode/laravel-permission-name-generator)
44

5-
This package will generate permission names from route names. Permissions are grouped by controller name. These permission names can be usefull for authorization (role-permission base system)
6-
7-
## Example
8-
### Generate permission view
9-
![Stats](img/permission-view.png)
10-
11-
**In controller:**
12-
13-
```php
14-
class RoleController extends Controller
15-
{
16-
public function permissionsShow($id)
17-
{
18-
$role = Role::query()->findOrFail($id);
19-
20-
return PermissionsView::withRolePermissions(
21-
$role->role_name,
22-
json_decode($role->role_permissions), // assume role permissions stored as json encoded
23-
route('create-role-permission', $role->id) // permission save url for a role
24-
)->view('app.role.permissions');
25-
}
26-
}
27-
```
28-
**In view (blade) file:**
29-
```html
30-
<div class="permissions">
31-
{!! $permissionCards !!}
32-
</div>
33-
34-
......
35-
<!-- generate scripts -->
36-
{!! $permissionScripts !!}
37-
```
38-
**Saving permissions for a role:**
39-
```php
40-
Route::post('/role/{id}/permissions/create',[RoleController::class,'permissionStore'])->name('create-role-permission');
41-
```
42-
```php
43-
use \Illuminate\Http\Request;
44-
class RoleController extends Controller
45-
{
46-
public function permissionStore(Request $request,$id)
47-
{
48-
$role = Role::find($id);
49-
50-
$role->role_permissions = json_encode($request->get('permissions')); // get the submitted permissions
51-
$role->save();
52-
53-
return response()->json('success',201);
54-
}
55-
}
56-
```
5+
This package will generate permission names from routes. In many application we create static permission names (ex: create-post, edit-post, delete-post) to check user's accessability, using the package can helps you to generate permission names dynamically.
576
# Requirements
587
- [PHP >= 7.1](https://www.php.net/)
598
- [Laravel 5.7|6.x|7.x|8.x](https://github.com/laravel/framework)
@@ -75,8 +24,14 @@ Publish default permission view files (optional)
7524
# Usage
7625

7726
## PermissionGenerator trait [Optional]
78-
While this package generate permission names from route names, in some cases we might need to exclude some permission names. To do so implement the **WithPermissionGenerator** contracts in the controller, then use the **PermissionGenerator** trait. We can use `permissionExcludeMethods()` to exclude permissions by route associative method. We can also define permission group name `permissionGroupTitle()`.
27+
While this package generate permission names from route names, in some cases we might need to exclude some routes so that it won't generate as permission names. To do so implement the **WithPermissionGenerator** contracts in the controller, then use the **PermissionGenerator** trait.
28+
29+
Available methods in **PermissionGenerator** trait
7930

31+
- `permissionExcludeMethods()` : use to exculde a route from being generated as permission name.
32+
- `permissionGroupTitle()`: Use to set group title for permissions
33+
34+
**Example**
8035
```php
8136
use App\Http\Controllers\Controller;
8237
use RadiateCode\LaravelRoutePermission\Contracts\WithPermissionGenerator;
@@ -88,121 +43,198 @@ class OfficeController extends Controller implements WithPermissionGenerator
8843

8944
public function __construct()
9045
{
91-
$this->permissionGroupTitle('Office Crud Permission')
92-
->permissionExcludeMethods('index','listDatatable'); // when necessary exclude specific routes by the controller methods
46+
$this->permissionGroupTitle('Office Crud Permission')->permissionExcludeMethods('index','listDatatable'); // index and listDatatable associate routes won't be generated as permission names
9347
}
9448
}
9549
```
9650

97-
> **PermissionGenerator** trait is optional. Because if no permissible title defined, then this package dynamically generate a title based on controller name, And routes/permissions can be excluded in the config file.
98-
99-
## Get Permissions
51+
> **PermissionGenerator** trait is optional. Because if no permissible title defined, then this package dynamically generate a title based on controller name, And routes can be excluded in the config file.
10052
101-
You can get permissible routes And make your own permissions view in order to set role permissions.
53+
## Get permissions names
10254

10355
RadiateCode\PermissionNameGenerator\Permissions::make()->get();
10456

10557
**Output**
10658

10759
![Stats](img/permissible-routes-output.png)
10860

109-
> Under the hood it gets all the routes which registered in **web.php** and only take those routes which has permission middleware. The permissible routes grouped by controller.
110-
11161
## Permission View Builder Facade
112-
If you don't want to make permission view by your own, then you can use predefined permissions view [**PermissionViewBuilder** facade].
62+
The package comes with predefined a view with permission names
11363

114-
See the above [example](#example)
64+
[**PermissionViewBuilder** facade].
11565

11666
**Builder methods:**
11767

118-
- permissionView() : generate bootstrap permissions card based on permissible routes, and config defined action buttons.
119-
- withRolePermissions($roleName,$rolePermissions) : it is used to select all the permissions that have access to a particular role.
120-
- permissionScripts($url = null) : generate functions for check all and uncheck all buttons. The **$url** param used to submit the selected permissions for specific role.
68+
- `view(string $view, array $data = [])`: set your view, this method will render your view with two predefined keys (permissionCards, permissionScripts) and put those keys according to you view layout
69+
70+
- `withRolePermissions(string $roleName,arra $rolePermissions,string $permissionsSaveUrl = null)`: This method helps you to pre-checked the permissions of a role, in the 3rd arg you can define a url where you can save the role permissions
71+
72+
### Submiting permissions can be get by
12173

122-
> **Note:** When submit the permissions from predefined view to any post routes you need to get the permissions by
12374
> ```php
12475
> $request->get('permissions'); // array of permissions
12576
> ```
12677
78+
## Example
79+
### Permissions view
80+
![Stats](img/permission-view.png)
81+
82+
**In controller:**
83+
84+
```php
85+
namespace RadiateCode\PermissionNameGenerator\Facades\PermissionsView;
86+
use App\Models\Role;
87+
88+
class RoleController extends Controller
89+
{
90+
public function permissionsShow($id)
91+
{
92+
$role = Role::query()->findOrFail($id);
93+
94+
return PermissionsView::withRolePermissions(
95+
$role->role_name,
96+
json_decode($role->role_permissions), // assume role permissions stored as json encoded
97+
route('create-role-permission', $role->id) // permission save url for a role
98+
)->view('app.role.permissions'); // your view
99+
}
100+
}
101+
```
102+
**Create the permission savings route**
103+
104+
```php
105+
Route::post('/role/{id}/permissions/create',[RoleController::class,'permissionStore'])->name('create-role-permission');
106+
```
107+
```php
108+
use \Illuminate\Http\Request;
109+
class RoleController extends Controller
110+
{
111+
public function permissionStore(Request $request,$id)
112+
{
113+
$role = Role::find($id);
114+
115+
$role->role_permissions = json_encode($request->get('permissions')); // get the submitted permissions
116+
$role->save();
117+
118+
return response()->json('success',201);
119+
}
120+
}
121+
```
122+
123+
**In app/role/permissions.blade.php file:**
124+
```html
125+
@extends('layouts.app')
126+
127+
@section('content')
128+
<div class="row">
129+
<div class="col-12">
130+
<div class="card card-dark">
131+
<div class="card-header">
132+
<h3 class="card-title">Role Permissions</h3>
133+
</div>
134+
<div class="card-body">
135+
<!-- the key generated by permission view builder of permission name generator -->
136+
{!! $permissionCards !!}
137+
</div>
138+
</div>
139+
</div>
140+
</div>
141+
@endsection
142+
143+
@push('js')
144+
<!-- the key generated by permission view builder of permission name generator -->
145+
{!! $permissionScripts !!}
146+
@endpush
147+
```
148+
149+
> The layout is only for demo purpose, you should only notice the `$permissionCards` and `$permissionScripts` variables, and put those acording to your view layout.
127150
128151
## Configuration
129152

130-
Config the **config/route-permission.php** file.
153+
Config the **config/permission-generator.php** file.
131154

132-
Define the name of the permission middlewares. The package recognise the route as permissible route by these middlewares.
155+
1. If route name contains any special char then split the the name by that char. It will use to generate route title. For example if route name is **create.post** then it's title would be **Create Post**
133156
```php
134157
/**
135-
* Permission middlewares
136-
*
137-
* [nt: define the middlewares by which we applied permissions]
158+
* Split route name by defined needle
138159
*/
139-
'permission-middlewares' => [
140-
// 'auth', 'role-permissions'
141-
],
160+
'route-name-splitter-needle' => '.',
142161
```
143-
If route name contains any special char then split the the name by that char. It will use to generate route title. For example if route name is **create.designation** then it's title would be **Create Designation**
162+
163+
2. You can defined custom permissions
144164
```php
145165
/**
146-
* Split route name by defined character
166+
* Custom permissions
147167
*/
148-
'route-name-splitter' => '.',
168+
'custom-permissions' => [
169+
//
170+
],
149171
```
150-
Exclude routes by route name. If we don't want to include any routes as permissible routes then we can exclude those in here.
172+
> Example
173+
> ```php
174+
> 'custom-permissions' = [
175+
> 'post-permission' => 'approve-permission',
176+
> 'user-permission' => ['active-user','inactive-user']
177+
> ]
178+
>```
179+
180+
3. Each route associate with controllers, so you have to define the controller namespace so that the generator can generate permission names from those route associate controllers. By default all the controllers associate routes will be generated as permission names.
181+
151182
```php
152183
/**
153-
* Exclude routes by route name
184+
* Define controller namespace
185+
*
186+
* [NT: permissions will be generated from those controller which contains the defined prefix]
154187
*/
155-
'exclude-routes' => [
156-
// route.name
188+
'controller-namespace-prefixes' => [
189+
'App\Http\Controllers',
157190
],
158191
```
159-
Exclude routes by controller. If we want to exclude all routes of a controller then we can exclude it here
192+
4. Exclude routes by controller. If we want to exclude routes of a controller then we can exclude it. By default all auth related routes will be excluded from being generated as permission names.
160193

161194
```php
162-
/**
163-
* Exclude routes by controller
195+
/**
196+
* Exclude routes by controller or controller namespace-prefix
164197
*
165-
* [NT: We can exclude routes by controllers. All the routes associated with controller will be excluded]
198+
* [NT: We can exclude routes by defining controller name or namespace-prefix. All the routes associated with controller will be excluded]
166199
*/
167-
'exclude-controllers' => [
168-
/**
169-
* exclude every route which associate with WelcomeController
170-
*/
171-
// WelcomeController::class
200+
'exclude-controllers' => [
201+
/*
202+
* exclude every route which associate with the prefix namespace
203+
*/
204+
'App\Http\Controllers\Auth',
172205
],
173206
```
174-
Caching the permissible routes
207+
208+
5. **Or,** we can exclude routes by route name
209+
175210
```php
176-
/**
177-
* Cache the permissible routes
211+
/**
212+
* Exclude routes by route name
178213
*/
179-
'cache-routes' => [
180-
'cacheable' => true,
181-
'cache-driver' => env('CACHE_DRIVER', 'file')
214+
'exclude-routes' => [
215+
// route.name
182216
],
183217
```
184-
Buttons generate in the permission view
218+
219+
6. Caching the permission names
220+
185221
```php
186222
/**
187-
* permission button used to checked / unchecked all routes
188-
* and save permissions for a particular role
189-
*
190-
* nt: extra button can be added
223+
* Cache the rendered permission names
191224
*/
192-
'permission-buttons' => [
193-
'<button type="button" class="btn btn-primary" onclick="checkAll()"><i class="fa fa-check-square"></i> Check All</button>',
194-
'<button type="button" class="btn btn-warning" onclick="uncheckAll()"><i class="fa fa-square"></i> Uncheck All </button>',
195-
'<button type="button" class="btn btn-success save-btn" onclick="saveRolePermissions()" title="save role permission"><i class="save-loader fa fa-save"></i> Save </button>',
225+
'cache-permissions' => [
226+
'cacheable' => true,
227+
'cache-driver' => env('CACHE_DRIVER', 'file'),
196228
],
197229
```
198-
Permission card size (bootstrap grid)
230+
7. Permission card size (bootstrap grid)
199231
```php
200232
/**
201233
* Permission card size
202234
*
203-
* [nt: permissible card only works on bootstrap]
235+
* [NT: Predefined permission cards works on bootstrap]
204236
*/
205-
'card-size-class' => 'col-md-3 col-lg-3 col-sm-12',
237+
'card-size-class' => 'col-md-3 col-lg-3 col-sm-12',
206238
```
207239
## Contributing
208240
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

‎config/permission-generator.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
/**
1818
* Define controller namespace
1919
*
20-
* [NT: permissions will be generated from those controller which contains the prefix]
20+
* [NT: permissions will be generated from those controller which contains the defined prefix]
2121
*/
2222
'controller-namespace-prefixes' => [
2323
'App\Http\Controllers',
@@ -43,7 +43,7 @@
4343
],
4444

4545
/**
46-
* Cache the permissible routes
46+
* Cache the rendered permission names
4747
*/
4848
'cache-permissions' => [
4949
'cacheable' => true,
@@ -53,7 +53,7 @@
5353
/**
5454
* Permission card size
5555
*
56-
* [NT: Permissible card only works on bootstrap]
56+
* [NT: Predefined permission cards works on bootstrap]
5757
*/
5858
'card-size-class' => 'col-md-3 col-lg-3 col-sm-12',
5959
];

‎src/Permissions.php‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -140,9 +140,7 @@ protected function customPermissions(): Permissions
140140
if (is_array($customPermissions) && ! empty($customPermissions)) {
141141
foreach ($customPermissions as $key => $permission) {
142142
if (array_key_exists(0, $permission)
143-
&& is_array(
144-
$permission[0]
145-
)
143+
&& is_array($permission[0])
146144
) {
147145
foreach ($permission as $item) {
148146
$this->permissions[$key][] = $item;

0 commit comments

Comments
 (0)