docs: add README_CN.md
This commit is contained in:
parent
bb566321bb
commit
bfeb6d13bf
743
README.md
743
README.md
|
@ -1,368 +1,375 @@
|
||||||
<h1 align="center">
|
<h1 align="center">
|
||||||
Laravel Authorization
|
Laravel Authorization
|
||||||
</h1>
|
</h1>
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<strong>Laravel-authz is an authorization library for the laravel framework.</strong>
|
<strong>Laravel-authz is an authorization library for the laravel framework.</strong>
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<a href="https://github.com/php-casbin/laravel-authz/actions">
|
<a href="https://github.com/php-casbin/laravel-authz/actions">
|
||||||
<img src="https://github.com/php-casbin/laravel-authz/workflows/build/badge.svg?branch=master" alt="Build Status">
|
<img src="https://github.com/php-casbin/laravel-authz/workflows/build/badge.svg?branch=master" alt="Build Status">
|
||||||
</a>
|
</a>
|
||||||
<a href="https://coveralls.io/github/php-casbin/laravel-authz">
|
<a href="https://coveralls.io/github/php-casbin/laravel-authz">
|
||||||
<img src="https://coveralls.io/repos/github/php-casbin/laravel-authz/badge.svg" alt="Coverage Status">
|
<img src="https://coveralls.io/repos/github/php-casbin/laravel-authz/badge.svg" alt="Coverage Status">
|
||||||
</a>
|
</a>
|
||||||
<a href="https://packagist.org/packages/casbin/laravel-authz">
|
<a href="https://packagist.org/packages/casbin/laravel-authz">
|
||||||
<img src="https://poser.pugx.org/casbin/laravel-authz/v/stable" alt="Latest Stable Version">
|
<img src="https://poser.pugx.org/casbin/laravel-authz/v/stable" alt="Latest Stable Version">
|
||||||
</a>
|
</a>
|
||||||
<a href="https://packagist.org/packages/casbin/laravel-authz">
|
<a href="https://packagist.org/packages/casbin/laravel-authz">
|
||||||
<img src="https://poser.pugx.org/casbin/laravel-authz/downloads" alt="Total Downloads">
|
<img src="https://poser.pugx.org/casbin/laravel-authz/downloads" alt="Total Downloads">
|
||||||
</a>
|
</a>
|
||||||
<a href="https://packagist.org/packages/casbin/laravel-authz">
|
<a href="https://packagist.org/packages/casbin/laravel-authz">
|
||||||
<img src="https://poser.pugx.org/casbin/laravel-authz/license" alt="License">
|
<img src="https://poser.pugx.org/casbin/laravel-authz/license" alt="License">
|
||||||
</a>
|
</a>
|
||||||
</p>
|
</p>
|
||||||
|
[Chinese Version](https://github.com/php-casbin/laravel-authz/blob/master/README_CN.md)
|
||||||
It's based on [Casbin](https://github.com/php-casbin/php-casbin), an authorization library that supports access control models like ACL, RBAC, ABAC.
|
|
||||||
|
It's based on [Casbin](https://github.com/php-casbin/php-casbin), an authorization library that supports access control models like ACL, RBAC, ABAC.
|
||||||
All you need to learn to use `Casbin` first.
|
|
||||||
|
All you need to learn to use `Casbin` first.
|
||||||
* [Installation](#installation)
|
|
||||||
* [Usage](#usage)
|
* [Installation](#installation)
|
||||||
* [Quick start](#quick-start)
|
* [Usage](#usage)
|
||||||
* [Using Enforcer Api](#using-enforcer-api)
|
* [Quick start](#quick-start)
|
||||||
* [Using a middleware](#using-a-middleware)
|
* [Using Enforcer Api](#using-enforcer-api)
|
||||||
* [basic Enforcer Middleware](#basic-enforcer-middleware)
|
* [Using a middleware](#using-a-middleware)
|
||||||
* [HTTP Request Middleware ( RESTful is also supported )](#http-request-middleware--restful-is-also-supported-)
|
* [basic Enforcer Middleware](#basic-enforcer-middleware)
|
||||||
* [Multiple enforcers](#multiple-enforcers)
|
* [HTTP Request Middleware ( RESTful is also supported )](#http-request-middleware--restful-is-also-supported-)
|
||||||
* [Using artisan commands](#using-artisan-commands)
|
* [Multiple enforcers](#multiple-enforcers)
|
||||||
* [Cache](#using-cache)
|
* [Using artisan commands](#using-artisan-commands)
|
||||||
* [Thinks](#thinks)
|
* [Cache](#using-cache)
|
||||||
* [License](#license)
|
* [Thinks](#thinks)
|
||||||
|
* [License](#license)
|
||||||
## Installation
|
|
||||||
|
## Installation
|
||||||
Require this package in the `composer.json` of your Laravel project. This will download the package.
|
|
||||||
|
Require this package in the `composer.json` of your Laravel project. Then execute the following command on the command line. This will download the package.
|
||||||
```
|
|
||||||
composer require casbin/laravel-authz
|
```php
|
||||||
```
|
composer install
|
||||||
|
```
|
||||||
The `Lauthz\LauthzServiceProvider` is `auto-discovered` and registered by default, but if you want to register it yourself:
|
|
||||||
|
Or use the command line tool to enter the root directory of your Laravel application and run the following `composer` command to install the extension directly.
|
||||||
Add the ServiceProvider in `config/app.php`
|
|
||||||
|
```
|
||||||
```php
|
composer require casbin/laravel-authz
|
||||||
'providers' => [
|
```
|
||||||
/*
|
|
||||||
* Package Service Providers...
|
The `Lauthz\LauthzServiceProvider` is `auto-discovered` and registered by default, but if you want to register it yourself:
|
||||||
*/
|
|
||||||
Lauthz\LauthzServiceProvider::class,
|
Add the ServiceProvider in `config/app.php`
|
||||||
]
|
|
||||||
```
|
```php
|
||||||
|
'providers' => [
|
||||||
The Enforcer facade is also `auto-discovered`, but if you want to add it manually:
|
/*
|
||||||
|
* Package Service Providers...
|
||||||
Add the Facade in `config/app.php`
|
*/
|
||||||
|
Lauthz\LauthzServiceProvider::class,
|
||||||
```php
|
]
|
||||||
'aliases' => [
|
```
|
||||||
// ...
|
|
||||||
'Enforcer' => Lauthz\Facades\Enforcer::class,
|
The Enforcer facade is also `auto-discovered`, but if you want to add it manually:
|
||||||
]
|
|
||||||
```
|
Add the Facade in `config/app.php`
|
||||||
|
|
||||||
To publish the config, run the vendor publish command:
|
```php
|
||||||
|
'aliases' => [
|
||||||
```
|
// ...
|
||||||
php artisan vendor:publish
|
'Enforcer' => Lauthz\Facades\Enforcer::class,
|
||||||
```
|
]
|
||||||
|
```
|
||||||
This will create a new model config file named `config/lauthz-rbac-model.conf` and a new lauthz config file named `config/lauthz.php`.
|
|
||||||
|
To publish the config, run the vendor publish command:
|
||||||
|
|
||||||
To migrate the migrations, run the migrate command:
|
```
|
||||||
|
php artisan vendor:publish
|
||||||
```
|
```
|
||||||
php artisan migrate
|
|
||||||
```
|
This will create a new model config file named `config/lauthz-rbac-model.conf` and a new lauthz config file named `config/lauthz.php`.
|
||||||
|
|
||||||
This will create a new table named `rules`
|
|
||||||
|
To migrate the migrations, run the migrate command:
|
||||||
|
|
||||||
## Usage
|
```
|
||||||
|
php artisan migrate
|
||||||
### Quick start
|
```
|
||||||
|
|
||||||
Once installed you can do stuff like this:
|
This will create a new table named `rules`
|
||||||
|
|
||||||
```php
|
|
||||||
|
## Usage
|
||||||
use Enforcer;
|
|
||||||
|
### Quick start
|
||||||
// adds permissions to a user
|
|
||||||
Enforcer::addPermissionForUser('eve', 'articles', 'read');
|
Once installed you can do stuff like this:
|
||||||
// adds a role for a user.
|
|
||||||
Enforcer::addRoleForUser('eve', 'writer');
|
```php
|
||||||
// adds permissions to a rule
|
|
||||||
Enforcer::addPolicy('writer', 'articles','edit');
|
use Enforcer;
|
||||||
|
|
||||||
```
|
// adds permissions to a user
|
||||||
|
Enforcer::addPermissionForUser('eve', 'articles', 'read');
|
||||||
You can check if a user has a permission like this:
|
// adds a role for a user.
|
||||||
|
Enforcer::addRoleForUser('eve', 'writer');
|
||||||
```php
|
// adds permissions to a rule
|
||||||
// to check if a user has permission
|
Enforcer::addPolicy('writer', 'articles','edit');
|
||||||
if (Enforcer::enforce("eve", "articles", "edit")) {
|
|
||||||
// permit eve to edit articles
|
```
|
||||||
} else {
|
|
||||||
// deny the request, show an error
|
You can check if a user has a permission like this:
|
||||||
}
|
|
||||||
|
```php
|
||||||
```
|
// to check if a user has permission
|
||||||
|
if (Enforcer::enforce("eve", "articles", "edit")) {
|
||||||
### Using Enforcer Api
|
// permit eve to edit articles
|
||||||
|
} else {
|
||||||
It provides a very rich api to facilitate various operations on the Policy:
|
// deny the request, show an error
|
||||||
|
}
|
||||||
Gets all roles:
|
|
||||||
|
```
|
||||||
```php
|
|
||||||
Enforcer::getAllRoles(); // ['writer', 'reader']
|
### Using Enforcer Api
|
||||||
```
|
|
||||||
|
It provides a very rich api to facilitate various operations on the Policy:
|
||||||
Gets all the authorization rules in the policy.:
|
|
||||||
|
Gets all roles:
|
||||||
```php
|
|
||||||
Enforcer::getPolicy();
|
```php
|
||||||
```
|
Enforcer::getAllRoles(); // ['writer', 'reader']
|
||||||
|
```
|
||||||
Gets the roles that a user has.
|
|
||||||
|
Gets all the authorization rules in the policy.:
|
||||||
```php
|
|
||||||
Enforcer::getRolesForUser('eve'); // ['writer']
|
```php
|
||||||
```
|
Enforcer::getPolicy();
|
||||||
|
```
|
||||||
Gets the users that has a role.
|
|
||||||
|
Gets the roles that a user has.
|
||||||
```php
|
|
||||||
Enforcer::getUsersForRole('writer'); // ['eve']
|
```php
|
||||||
```
|
Enforcer::getRolesForUser('eve'); // ['writer']
|
||||||
|
```
|
||||||
Determines whether a user has a role.
|
|
||||||
|
Gets the users that has a role.
|
||||||
```php
|
|
||||||
Enforcer::hasRoleForUser('eve', 'writer'); // true or false
|
```php
|
||||||
```
|
Enforcer::getUsersForRole('writer'); // ['eve']
|
||||||
|
```
|
||||||
Adds a role for a user.
|
|
||||||
|
Determines whether a user has a role.
|
||||||
```php
|
|
||||||
Enforcer::addRoleForUser('eve', 'writer');
|
```php
|
||||||
```
|
Enforcer::hasRoleForUser('eve', 'writer'); // true or false
|
||||||
|
```
|
||||||
Adds a permission for a user or role.
|
|
||||||
|
Adds a role for a user.
|
||||||
```php
|
|
||||||
// to user
|
```php
|
||||||
Enforcer::addPermissionForUser('eve', 'articles', 'read');
|
Enforcer::addRoleForUser('eve', 'writer');
|
||||||
// to role
|
```
|
||||||
Enforcer::addPermissionForUser('writer', 'articles','edit');
|
|
||||||
```
|
Adds a permission for a user or role.
|
||||||
|
|
||||||
Deletes a role for a user.
|
```php
|
||||||
|
// to user
|
||||||
```php
|
Enforcer::addPermissionForUser('eve', 'articles', 'read');
|
||||||
Enforcer::deleteRoleForUser('eve', 'writer');
|
// to role
|
||||||
```
|
Enforcer::addPermissionForUser('writer', 'articles','edit');
|
||||||
|
```
|
||||||
Deletes all roles for a user.
|
|
||||||
|
Deletes a role for a user.
|
||||||
```php
|
|
||||||
Enforcer::deleteRolesForUser('eve');
|
```php
|
||||||
```
|
Enforcer::deleteRoleForUser('eve', 'writer');
|
||||||
|
```
|
||||||
Deletes a role.
|
|
||||||
|
Deletes all roles for a user.
|
||||||
```php
|
|
||||||
Enforcer::deleteRole('writer');
|
```php
|
||||||
```
|
Enforcer::deleteRolesForUser('eve');
|
||||||
|
```
|
||||||
Deletes a permission.
|
|
||||||
|
Deletes a role.
|
||||||
```php
|
|
||||||
Enforcer::deletePermission('articles', 'read'); // returns false if the permission does not exist (aka not affected).
|
```php
|
||||||
```
|
Enforcer::deleteRole('writer');
|
||||||
|
```
|
||||||
Deletes a permission for a user or role.
|
|
||||||
|
Deletes a permission.
|
||||||
```php
|
|
||||||
Enforcer::deletePermissionForUser('eve', 'articles', 'read');
|
```php
|
||||||
```
|
Enforcer::deletePermission('articles', 'read'); // returns false if the permission does not exist (aka not affected).
|
||||||
|
```
|
||||||
Deletes permissions for a user or role.
|
|
||||||
|
Deletes a permission for a user or role.
|
||||||
```php
|
|
||||||
// to user
|
```php
|
||||||
Enforcer::deletePermissionsForUser('eve');
|
Enforcer::deletePermissionForUser('eve', 'articles', 'read');
|
||||||
// to role
|
```
|
||||||
Enforcer::deletePermissionsForUser('writer');
|
|
||||||
```
|
Deletes permissions for a user or role.
|
||||||
|
|
||||||
Gets permissions for a user or role.
|
```php
|
||||||
|
// to user
|
||||||
```php
|
Enforcer::deletePermissionsForUser('eve');
|
||||||
Enforcer::getPermissionsForUser('eve'); // return array
|
// to role
|
||||||
```
|
Enforcer::deletePermissionsForUser('writer');
|
||||||
|
```
|
||||||
Determines whether a user has a permission.
|
|
||||||
|
Gets permissions for a user or role.
|
||||||
```php
|
|
||||||
Enforcer::hasPermissionForUser('eve', 'articles', 'read'); // true or false
|
```php
|
||||||
```
|
Enforcer::getPermissionsForUser('eve'); // return array
|
||||||
|
```
|
||||||
See [Casbin API](https://casbin.org/docs/en/management-api) for more APIs.
|
|
||||||
|
Determines whether a user has a permission.
|
||||||
### Using a middleware
|
|
||||||
|
```php
|
||||||
This package comes with `EnforcerMiddleware`, `RequestMiddleware` middlewares. You can add them inside your `app/Http/Kernel.php` file.
|
Enforcer::hasPermissionForUser('eve', 'articles', 'read'); // true or false
|
||||||
|
```
|
||||||
```php
|
|
||||||
protected $routeMiddleware = [
|
See [Casbin API](https://casbin.org/docs/en/management-api) for more APIs.
|
||||||
// ...
|
|
||||||
// a basic Enforcer Middleware
|
### Using a middleware
|
||||||
'enforcer' => \Lauthz\Middlewares\EnforcerMiddleware::class,
|
|
||||||
// an HTTP Request Middleware
|
This package comes with `EnforcerMiddleware`, `RequestMiddleware` middlewares. You can add them inside your `app/Http/Kernel.php` file.
|
||||||
'http_request' => \Lauthz\Middlewares\RequestMiddleware::class,
|
|
||||||
];
|
```php
|
||||||
```
|
protected $routeMiddleware = [
|
||||||
|
// ...
|
||||||
#### basic Enforcer Middleware
|
// a basic Enforcer Middleware
|
||||||
|
'enforcer' => \Lauthz\Middlewares\EnforcerMiddleware::class,
|
||||||
Then you can protect your routes using middleware rules:
|
// an HTTP Request Middleware
|
||||||
|
'http_request' => \Lauthz\Middlewares\RequestMiddleware::class,
|
||||||
```php
|
];
|
||||||
Route::group(['middleware' => ['enforcer:articles,read']], function () {
|
```
|
||||||
// pass
|
|
||||||
});
|
#### basic Enforcer Middleware
|
||||||
```
|
|
||||||
|
Then you can protect your routes using middleware rules:
|
||||||
#### HTTP Request Middleware ( RESTful is also supported )
|
|
||||||
|
```php
|
||||||
If you need to authorize a Request,you need to define the model configuration first in `config/lauthz-rbac-model.conf`:
|
Route::group(['middleware' => ['enforcer:articles,read']], function () {
|
||||||
|
// pass
|
||||||
```ini
|
});
|
||||||
[request_definition]
|
```
|
||||||
r = sub, obj, act
|
|
||||||
|
#### HTTP Request Middleware ( RESTful is also supported )
|
||||||
[policy_definition]
|
|
||||||
p = sub, obj, act
|
If you need to authorize a Request,you need to define the model configuration first in `config/lauthz-rbac-model.conf`:
|
||||||
|
|
||||||
[role_definition]
|
```ini
|
||||||
g = _, _
|
[request_definition]
|
||||||
|
r = sub, obj, act
|
||||||
[policy_effect]
|
|
||||||
e = some(where (p.eft == allow))
|
[policy_definition]
|
||||||
|
p = sub, obj, act
|
||||||
[matchers]
|
|
||||||
m = g(r.sub, p.sub) && keyMatch2(r.obj, p.obj) && regexMatch(r.act, p.act)
|
[role_definition]
|
||||||
```
|
g = _, _
|
||||||
|
|
||||||
Then, using middleware rules:
|
[policy_effect]
|
||||||
|
e = some(where (p.eft == allow))
|
||||||
```php
|
|
||||||
Route::group(['middleware' => ['http_request']], function () {
|
[matchers]
|
||||||
Route::resource('photo', 'PhotoController');
|
m = g(r.sub, p.sub) && keyMatch2(r.obj, p.obj) && regexMatch(r.act, p.act)
|
||||||
});
|
```
|
||||||
```
|
|
||||||
|
Then, using middleware rules:
|
||||||
### Multiple enforcers
|
|
||||||
|
```php
|
||||||
If you need multiple permission controls in your project, you can configure multiple enforcers.
|
Route::group(['middleware' => ['http_request']], function () {
|
||||||
|
Route::resource('photo', 'PhotoController');
|
||||||
In the lauthz file, it should be like this:
|
});
|
||||||
|
```
|
||||||
```php
|
|
||||||
return [
|
### Multiple enforcers
|
||||||
'default' => 'basic',
|
|
||||||
|
If you need multiple permission controls in your project, you can configure multiple enforcers.
|
||||||
'basic' => [
|
|
||||||
'model' => [
|
In the lauthz file, it should be like this:
|
||||||
// ...
|
|
||||||
],
|
```php
|
||||||
|
return [
|
||||||
'adapter' => Lauthz\Adapters\DatabaseAdapter::class,
|
'default' => 'basic',
|
||||||
// ...
|
|
||||||
],
|
'basic' => [
|
||||||
|
'model' => [
|
||||||
'second' => [
|
// ...
|
||||||
'model' => [
|
],
|
||||||
// ...
|
|
||||||
],
|
'adapter' => Lauthz\Adapters\DatabaseAdapter::class,
|
||||||
|
// ...
|
||||||
'adapter' => Lauthz\Adapters\DatabaseAdapter::class,
|
],
|
||||||
// ...
|
|
||||||
],
|
'second' => [
|
||||||
];
|
'model' => [
|
||||||
|
// ...
|
||||||
```
|
],
|
||||||
|
|
||||||
Then you can choose which enforcers to use.
|
'adapter' => Lauthz\Adapters\DatabaseAdapter::class,
|
||||||
|
// ...
|
||||||
```php
|
],
|
||||||
Enforcer::guard('second')->enforce("eve", "articles", "edit");
|
];
|
||||||
```
|
|
||||||
|
```
|
||||||
|
|
||||||
### Using artisan commands
|
Then you can choose which enforcers to use.
|
||||||
|
|
||||||
You can create a policy from a console with artisan commands.
|
```php
|
||||||
|
Enforcer::guard('second')->enforce("eve", "articles", "edit");
|
||||||
To user:
|
```
|
||||||
|
|
||||||
```bash
|
|
||||||
php artisan policy:add eve,articles,read
|
### Using artisan commands
|
||||||
```
|
|
||||||
|
You can create a policy from a console with artisan commands.
|
||||||
To Role:
|
|
||||||
|
To user:
|
||||||
```bash
|
|
||||||
php artisan policy:add writer,articles,edit
|
```bash
|
||||||
```
|
php artisan policy:add eve,articles,read
|
||||||
|
```
|
||||||
Adds a role for a user:
|
|
||||||
|
To Role:
|
||||||
```bash
|
|
||||||
php artisan role:assign eve writer
|
```bash
|
||||||
```
|
php artisan policy:add writer,articles,edit
|
||||||
|
```
|
||||||
### Using cache
|
|
||||||
|
Adds a role for a user:
|
||||||
Authorization rules are cached to speed up performance. The default is off.
|
|
||||||
|
```bash
|
||||||
Sets your own cache configs in Laravel's `config/lauthz.php`.
|
php artisan role:assign eve writer
|
||||||
|
```
|
||||||
```php
|
|
||||||
'cache' => [
|
### Using cache
|
||||||
// changes whether Lauthz will cache the rules.
|
|
||||||
'enabled' => false,
|
Authorization rules are cached to speed up performance. The default is off.
|
||||||
|
|
||||||
// cache store
|
Sets your own cache configs in Laravel's `config/lauthz.php`.
|
||||||
'store' => 'default',
|
|
||||||
|
```php
|
||||||
// cache Key
|
'cache' => [
|
||||||
'key' => 'rules',
|
// changes whether Lauthz will cache the rules.
|
||||||
|
'enabled' => false,
|
||||||
// ttl \DateTimeInterface|\DateInterval|int|null
|
|
||||||
'ttl' => 24 * 60,
|
// cache store
|
||||||
],
|
'store' => 'default',
|
||||||
```
|
|
||||||
|
// cache Key
|
||||||
## Thinks
|
'key' => 'rules',
|
||||||
|
|
||||||
[Casbin](https://github.com/php-casbin/php-casbin) in Laravel. You can find the full documentation of Casbin [on the website](https://casbin.org/).
|
// ttl \DateTimeInterface|\DateInterval|int|null
|
||||||
|
'ttl' => 24 * 60,
|
||||||
## License
|
],
|
||||||
|
```
|
||||||
This project is licensed under the [Apache 2.0 license](LICENSE).
|
|
||||||
|
## Thinks
|
||||||
|
|
||||||
|
[Casbin](https://github.com/php-casbin/php-casbin) in Laravel. You can find the full documentation of Casbin [on the website](https://casbin.org/).
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
This project is licensed under the [Apache 2.0 license](LICENSE).
|
||||||
|
|
|
@ -0,0 +1,374 @@
|
||||||
|
<h1 align="center">
|
||||||
|
Laravel Authorization
|
||||||
|
</h1>
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<strong>Laravel-authz 是一个专为 Laravel 打造的授权(角色和权限控制)工具</strong>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<a href="https://github.com/php-casbin/laravel-authz/actions">
|
||||||
|
<img src="https://github.com/php-casbin/laravel-authz/workflows/build/badge.svg?branch=master" alt="Build Status">
|
||||||
|
</a>
|
||||||
|
<a href="https://coveralls.io/github/php-casbin/laravel-authz">
|
||||||
|
<img src="https://coveralls.io/repos/github/php-casbin/laravel-authz/badge.svg" alt="Coverage Status">
|
||||||
|
</a>
|
||||||
|
<a href="https://packagist.org/packages/casbin/laravel-authz">
|
||||||
|
<img src="https://poser.pugx.org/casbin/laravel-authz/v/stable" alt="Latest Stable Version">
|
||||||
|
</a>
|
||||||
|
<a href="https://packagist.org/packages/casbin/laravel-authz">
|
||||||
|
<img src="https://poser.pugx.org/casbin/laravel-authz/downloads" alt="Total Downloads">
|
||||||
|
</a>
|
||||||
|
<a href="https://packagist.org/packages/casbin/laravel-authz">
|
||||||
|
<img src="https://poser.pugx.org/casbin/laravel-authz/license" alt="License">
|
||||||
|
</a>
|
||||||
|
</p>
|
||||||
|
[英文版本](https://github.com/php-casbin/laravel-authz/blob/master/README.md)
|
||||||
|
|
||||||
|
它基于 [PHP-Casbin](https://github.com/php-casbin/php-casbin), 一个强大的、高效的开源访问控制框架,支持基于`ACL`, `RBAC`, `ABAC`等访问控制模型。
|
||||||
|
|
||||||
|
在这之前,你需要先了解 [Casbin](https://github.com/php-casbin/php-casbin) 的相关知识。
|
||||||
|
|
||||||
|
* [安装](#安装)
|
||||||
|
* [用法](#用法)
|
||||||
|
* [快速开始](#快速开始)
|
||||||
|
* [使用 Enforcer Api](#使用-enforcer-api)
|
||||||
|
* [使用中间件](#使用中间件)
|
||||||
|
* [基础 Enforcer 中间件](#基础-enforcer-中间件)
|
||||||
|
* [HTTP 请求中间件 ( 同时支持RESTful )](#http-请求中间件--同时支持-restful-)
|
||||||
|
* [多个 Enforcer 设置](#多个-Enforcer-设置)
|
||||||
|
* [使用 artisan 命令](#使用-artisan-命令)
|
||||||
|
* [缓存](#使用缓存)
|
||||||
|
* [感谢](#感谢)
|
||||||
|
* [License](#license)
|
||||||
|
|
||||||
|
## 安装
|
||||||
|
|
||||||
|
在 Laravel 应用根目录下的 `composer.json` 文件中指定该扩展,然后运行下面的 `composer` 命令。该扩展会被下载
|
||||||
|
|
||||||
|
```
|
||||||
|
composer install
|
||||||
|
```
|
||||||
|
|
||||||
|
或者使用命令行工具进入 Laravel 应用的根目录,运行下面的 `composer` 命令来直接安装该扩展
|
||||||
|
|
||||||
|
```php
|
||||||
|
composer require casbin/laravel-authz
|
||||||
|
```
|
||||||
|
|
||||||
|
`Lauthz\LauthzServiceProvider` 默认会被自动发现并注册,但你也可以像下面这样手动注册它
|
||||||
|
|
||||||
|
在 `config/app.php` 文件中添加该服务提供者
|
||||||
|
|
||||||
|
```php
|
||||||
|
'providers' => [
|
||||||
|
/*
|
||||||
|
* Package Service Providers...
|
||||||
|
*/
|
||||||
|
Lauthz\LauthzServiceProvider::class,
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
`Enforcer` 门面也会被自动发现,但你也可以像下面这样手动添加它
|
||||||
|
|
||||||
|
在 `config/app.php` 文件中添加该门面
|
||||||
|
|
||||||
|
```php
|
||||||
|
'aliases' => [
|
||||||
|
// ...
|
||||||
|
'Enforcer' => Lauthz\Facades\Enforcer::class,
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
如果想要发布该扩展的设置文件,运行下面的 `artisan` 命令
|
||||||
|
|
||||||
|
```
|
||||||
|
php artisan vendor:publish
|
||||||
|
```
|
||||||
|
|
||||||
|
这会在 Laravel 的 `config/` 目录下生产一个叫做 `lauthz-rbac-model.conf` 的模型设置文件,和一个叫做 `lauthz.php` 的扩展设置文件
|
||||||
|
|
||||||
|
|
||||||
|
如果想要创建扩展对应的数据库文件,运行下面的 `artisan` 命令
|
||||||
|
|
||||||
|
```
|
||||||
|
php artisan migrate
|
||||||
|
```
|
||||||
|
|
||||||
|
这会创建一个叫做 `rules` 的数据表
|
||||||
|
|
||||||
|
|
||||||
|
## 用法
|
||||||
|
|
||||||
|
### 快速开始
|
||||||
|
|
||||||
|
安装成功后,可以这样使用:
|
||||||
|
|
||||||
|
```php
|
||||||
|
use Enforcer;
|
||||||
|
|
||||||
|
// adds permissions to a user
|
||||||
|
Enforcer::addPermissionForUser('eve', 'articles', 'read');
|
||||||
|
// adds a role for a user.
|
||||||
|
Enforcer::addRoleForUser('eve', 'writer');
|
||||||
|
// adds permissions to a rule
|
||||||
|
Enforcer::addPolicy('writer', 'articles','edit');
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
你可以检查一个用户是否拥有某个权限:
|
||||||
|
|
||||||
|
```php
|
||||||
|
// to check if a user has permission
|
||||||
|
if (Enforcer::enforce("eve", "articles", "edit")) {
|
||||||
|
// permit eve to edit articles
|
||||||
|
} else {
|
||||||
|
// deny the request, show an error
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
### 使用 Enforcer Api
|
||||||
|
|
||||||
|
它提供了非常丰富的 `API`,以促进对 `Policy` 的各种操作:
|
||||||
|
|
||||||
|
获取所有角色:
|
||||||
|
|
||||||
|
```php
|
||||||
|
Enforcer::getAllRoles(); // ['writer', 'reader']
|
||||||
|
```
|
||||||
|
|
||||||
|
获取所有的角色的授权规则:
|
||||||
|
|
||||||
|
```php
|
||||||
|
Enforcer::getPolicy();
|
||||||
|
```
|
||||||
|
|
||||||
|
获取某个用户的所有角色:
|
||||||
|
|
||||||
|
```php
|
||||||
|
Enforcer::getRolesForUser('eve'); // ['writer']
|
||||||
|
```
|
||||||
|
|
||||||
|
获取担任某个角色的所有用户:
|
||||||
|
|
||||||
|
```php
|
||||||
|
Enforcer::getUsersForRole('writer'); // ['eve']
|
||||||
|
```
|
||||||
|
|
||||||
|
决定用户是否拥有某个角色:
|
||||||
|
|
||||||
|
```php
|
||||||
|
Enforcer::hasRoleForUser('eve', 'writer'); // true or false
|
||||||
|
```
|
||||||
|
|
||||||
|
给用户添加角色:
|
||||||
|
|
||||||
|
```php
|
||||||
|
Enforcer::addRoleForUser('eve', 'writer');
|
||||||
|
```
|
||||||
|
|
||||||
|
赋予权限给某个用户或角色:
|
||||||
|
|
||||||
|
```php
|
||||||
|
// to user
|
||||||
|
Enforcer::addPermissionForUser('eve', 'articles', 'read');
|
||||||
|
// to role
|
||||||
|
Enforcer::addPermissionForUser('writer', 'articles','edit');
|
||||||
|
```
|
||||||
|
|
||||||
|
删除用户的角色:
|
||||||
|
|
||||||
|
```php
|
||||||
|
Enforcer::deleteRoleForUser('eve', 'writer');
|
||||||
|
```
|
||||||
|
|
||||||
|
删除某个用户的所有角色:
|
||||||
|
|
||||||
|
```php
|
||||||
|
Enforcer::deleteRolesForUser('eve');
|
||||||
|
```
|
||||||
|
|
||||||
|
删除单个角色:
|
||||||
|
|
||||||
|
```php
|
||||||
|
Enforcer::deleteRole('writer');
|
||||||
|
```
|
||||||
|
|
||||||
|
删除某个权限:
|
||||||
|
|
||||||
|
```php
|
||||||
|
Enforcer::deletePermission('articles', 'read'); // returns false if the permission does not exist (aka not affected).
|
||||||
|
```
|
||||||
|
|
||||||
|
删除某个用户或角色的权限:
|
||||||
|
|
||||||
|
```php
|
||||||
|
Enforcer::deletePermissionForUser('eve', 'articles', 'read');
|
||||||
|
```
|
||||||
|
|
||||||
|
删除某个用户或角色的所有权限:
|
||||||
|
|
||||||
|
```php
|
||||||
|
// to user
|
||||||
|
Enforcer::deletePermissionsForUser('eve');
|
||||||
|
// to role
|
||||||
|
Enforcer::deletePermissionsForUser('writer');
|
||||||
|
```
|
||||||
|
|
||||||
|
获取用户或角色的所有权限:
|
||||||
|
|
||||||
|
```php
|
||||||
|
Enforcer::getPermissionsForUser('eve'); // return array
|
||||||
|
```
|
||||||
|
|
||||||
|
决定某个用户是否拥有某个权限:
|
||||||
|
|
||||||
|
```php
|
||||||
|
Enforcer::hasPermissionForUser('eve', 'articles', 'read'); // true or false
|
||||||
|
```
|
||||||
|
|
||||||
|
更多 `API` 参考 [Casbin API](https://casbin.org/docs/en/management-api) 。
|
||||||
|
|
||||||
|
### 使用中间件
|
||||||
|
|
||||||
|
这个扩展包括 `EnforcerMiddleware`,`RequestMiddleware` 这两个中间件,你可以在你 Laravel 应用的 `app/Http/Kernel.php` 文件中添加上它们
|
||||||
|
|
||||||
|
```php
|
||||||
|
protected $routeMiddleware = [
|
||||||
|
// ...
|
||||||
|
// a basic Enforcer Middleware
|
||||||
|
'enforcer' => \Lauthz\Middlewares\EnforcerMiddleware::class,
|
||||||
|
// an HTTP Request Middleware
|
||||||
|
'http_request' => \Lauthz\Middlewares\RequestMiddleware::class,
|
||||||
|
];
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 基础 Enforcer 中间件
|
||||||
|
|
||||||
|
然后,你可以通过使用该中间件来保护对应的路由
|
||||||
|
|
||||||
|
```php
|
||||||
|
Route::group(['middleware' => ['enforcer:articles,read']], function () {
|
||||||
|
// pass
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
#### HTTP 请求中间件 ( 同时支持 RESTful )
|
||||||
|
|
||||||
|
如果你想要认证一个请求,你需要首先在 `config/lauthz-rbac-model.conf` 文件中定义相应的模型设置
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[request_definition]
|
||||||
|
r = sub, obj, act
|
||||||
|
|
||||||
|
[policy_definition]
|
||||||
|
p = sub, obj, act
|
||||||
|
|
||||||
|
[role_definition]
|
||||||
|
g = _, _
|
||||||
|
|
||||||
|
[policy_effect]
|
||||||
|
e = some(where (p.eft == allow))
|
||||||
|
|
||||||
|
[matchers]
|
||||||
|
m = g(r.sub, p.sub) && keyMatch2(r.obj, p.obj) && regexMatch(r.act, p.act)
|
||||||
|
```
|
||||||
|
|
||||||
|
然后,向该请求对应的路由添加中间件规则
|
||||||
|
|
||||||
|
```php
|
||||||
|
Route::group(['middleware' => ['http_request']], function () {
|
||||||
|
Route::resource('photo', 'PhotoController');
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### 多个 Enforcer 设置
|
||||||
|
|
||||||
|
如果在你的项目中你需要多种不同的权限控制,你可以添加多个 `Enforcer` 设置来实现
|
||||||
|
|
||||||
|
在该扩展的 `config/lauthz.php` 设置文件中,内容应该类似下面这样
|
||||||
|
|
||||||
|
```php
|
||||||
|
return [
|
||||||
|
'default' => 'basic',
|
||||||
|
|
||||||
|
'basic' => [
|
||||||
|
'model' => [
|
||||||
|
// ...
|
||||||
|
],
|
||||||
|
|
||||||
|
'adapter' => Lauthz\Adapters\DatabaseAdapter::class,
|
||||||
|
// ...
|
||||||
|
],
|
||||||
|
|
||||||
|
'second' => [
|
||||||
|
'model' => [
|
||||||
|
// ...
|
||||||
|
],
|
||||||
|
|
||||||
|
'adapter' => Lauthz\Adapters\DatabaseAdapter::class,
|
||||||
|
// ...
|
||||||
|
],
|
||||||
|
];
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
然后,你可以像下面这样来选择使用哪一个 `Enforcer` 设置
|
||||||
|
|
||||||
|
```php
|
||||||
|
Enforcer::guard('second')->enforce("eve", "articles", "edit");
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
### 使用 artisan 命令
|
||||||
|
|
||||||
|
你可以在命令行中通过 artisan 命令来创建一个授权策略
|
||||||
|
|
||||||
|
为用户添加权限
|
||||||
|
|
||||||
|
```bash
|
||||||
|
php artisan policy:add eve,articles,read
|
||||||
|
```
|
||||||
|
|
||||||
|
为角色添加权限
|
||||||
|
|
||||||
|
```bash
|
||||||
|
php artisan policy:add writer,articles,edit
|
||||||
|
```
|
||||||
|
|
||||||
|
为指定用户添加角色
|
||||||
|
|
||||||
|
```bash
|
||||||
|
php artisan role:assign eve writer
|
||||||
|
```
|
||||||
|
|
||||||
|
### 使用缓存
|
||||||
|
|
||||||
|
可以通过缓存授权规则来提升应用的执行速度,这一功能默认是关闭的
|
||||||
|
|
||||||
|
在 Laravel 应用的 `config/lauthz.php` 文件中添加你自己的缓存设置
|
||||||
|
|
||||||
|
```php
|
||||||
|
'cache' => [
|
||||||
|
// changes whether Lauthz will cache the rules.
|
||||||
|
'enabled' => false,
|
||||||
|
|
||||||
|
// cache store
|
||||||
|
'store' => 'default',
|
||||||
|
|
||||||
|
// cache Key
|
||||||
|
'key' => 'rules',
|
||||||
|
|
||||||
|
// ttl \DateTimeInterface|\DateInterval|int|null
|
||||||
|
'ttl' => 24 * 60,
|
||||||
|
],
|
||||||
|
```
|
||||||
|
|
||||||
|
## 感谢
|
||||||
|
|
||||||
|
[Casbin](https://github.com/php-casbin/php-casbin),你可以在其 [官网](https://casbin.org/) 上查看全部文档。
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
This project is licensed under the [Apache 2.0 license](LICENSE).
|
Loading…
Reference in New Issue