README

ACL - 访问控制列表。更确切地说，这是一个 RBAC - 基于角色的访问控制 - Laravel 4 的包。

简介

此 RBAC 插件通过角色定义用户权限，或将/检查权限设置到路由中。每个角色都有一个定义的权限数组。
每个用户被分配 1 个或多个角色，返回的权限是他分配的角色权限的并集。

角色示例：管理员、用户、受限用户、访客等。

安装
配置
钩子回调
路由
API
与模型一起使用
示例

##安装

使用 Composer 安装此包。编辑您的项目 composer.json 文件

"require": {
		"volicon/laravel-acl-rbac": "dev-master",
},
"minimum-stability": "dev"

接下来，从终端更新 Composer

  composer update

此操作完成后，将包添加到您的应用程序中，使用服务提供者。打开 app/config/app.php，编辑 providers 数组。

'providers' => array(
	'Volicon\Acl\AclServiceProvider',
),

建议添加新的别名到 aliases 数组。

'aliases' => array(
	'Acl'			  => 'Volicon\Acl\Facades\Acl',
	'AclUser'         => 'Volicon\Acl\AclUser',
	'AclRole'         => 'Volicon\Acl\AclRole',
)

最后一步是安装 ACL。您可以通过运行 artisan 命令轻松完成此操作

php artisan acl:install

这将为您创建数据库中的 4 个新表。

##配置

group_resources：您可以优化将资源放入组中。
组中的每个资源都称为组的子资源。在检查子资源的权限时，将返回组的权限。

例如，对于以下示例，对 users.show 或 users.select 的任何查询都将返回 users.view 权限。

'group_resources' =>
	'users.view' => [  // group 
		'users.index',
		'users.show', 
		'User.select',
	],
	'role.view' => [   // another group
		'role.index',
		'role.show', 
		'Role.select',
	]

allways_allow_resources：此处列出的任何资源都将始终返回 true，而无需对任何登录用户进行数据库查询。

	'allways_allow_resources' => [
		'local.viewCalendar'
	]

cache：可以使用 Laravel 的缓存与 Acl。设置缓存的键前缀。

'using_cache' => true
'cache_key' => '_volicon_acl_'

roleProviders 类定义角色的权限行为。例如，AdminRoleProvider 不允许将权限添加到角色中，并且始终返回不查询数据库的权限 true。您可以创建自定义 roleProviders，它具有一组定义的权限或从配置文件检查权限。默认 UsersRoleProvider 将返回角色本身。

roleProviders 类控制角色的添加、删除和更新。
例如：限制角色的用户。针对以下安全特性：创建新的管理员角色、将用户添加到管理员、删除管理员角色等。

您可以通过扩展 \Volicon\Acl\RoleProviders\AclRoleProvider 类并覆盖方法：addRole、removeRole、updateRole、getPermission 等，来添加自定义 roleProviders。

角色通过角色类型分配其 roleProviders。UsersRoleProvider 和 AdminRoleProvider 角色类型是默认提供的。

	'roleProviders' => [
		0 => '\Volicon\Acl\RoleProviders\UsersRoleProvider',
		1 => '\Volicon\Acl\RoleProviders\AdminRoleProvider'
	],

Roles：一个模型，它保存一组权限。模型的行为和控制由 roleProviders 类定义。该模型保存了分配给每个用户的数组。

role format:
[ 'name' => 'role name',
  'permissions' => array of permissions, //(optional, default defined by 'default_permission', unless permission is set by 'type')
  'type' => 0,   // (optional default 0) - roleProviders id, more on this later
  'default' => 1 // (optional default 0), if => 1  can not remove this role.
]

permissions format: 
[ "resource" => "permission name", 
  "values" => [], // (optional), array of resources ids
  "allowed" => 1  // (optional, default set by 'default_permission' ) 
]
//	"allowed": 1 means **incdule all**, 0 means **exclude all**.
//	"allowed" => 0 -- allow action **except** for resource with id in array, if 'values' array is empty dont allow.
//	"allowed" => 1 -- allow action **only**   for resource with id in array, if 'values' array is empty allow action.

示例：在此处，我们将为可以创建和编辑用户（除了 id === 1 的用户）的组管理员定义一个角色，但他不能删除任何用户。

// Note: permission values may have been overridden in roleProviders.  
// 		 for example if 'type' => 1, then role provider admin would override resource permissions limitation.

'roles' => [ 
			 [ 'name' => 'GroupAdmin', 
	   		   'permissions' => [
					 ["resource" => "user.create", "values" => [] 	,"allowed" => 1 ],
				     ["resource" => "user.edit",   "values" => [1]  ,"allowed" => 0 ],
					 ["resource" => "user.delete", "values" => []   ,"allowed" => 0 ],
			    ],
			   'type' => 0,   // value of roleProviders: 0 - user, 1 - Admin ( or custom if changed or added another roleProviders ).
			   'default' => 0 // (optional) if ( 'default' => 1 ) can not delete role. 
			 ],
			 [
			  'name' => 'Admin',
			  'type' => 1,   // AdminRoleProvider
			  'default' => 1 // can not delete role. 
			 ]
		   ]

default_permission: 未知资源和值的布尔行为。

'default_permission' => false

##动态更改权限的钩子。 registerHook -- 您可以将回调附加到资源，该回调将返回动态计算的权限。回调函数参数是 Volicon\Acl\AclPermission。

Acl::registerHook('media.list', function($permission){
	if(geoIp() !== 'Europe') {
		return new Volicon\Acl\AclPermission($permission->resource, [], false);  // dont allow
	}
	
	return $permission;  // else return defined role permission.
});

Acl::registerHook('ufo.list', function($permission){
	if(geoIp() === 'OuterSpace') {  
		$permission->allow = true; // manually set a permission.
		$permission->values[] = Auth::getUser()->user_id;
	return $permission;
});

##路由：(可选）为了检查每个网络请求，请添加以下代码。
不要忘记在 'group_resources' 中定义资源，并在角色中分配权限。

在 routes.php

	Route::group(array('before' => 'auth'), function() {	
		Route::resource('users', 'UsersController');
		Route::get('data', 'dataController@getData');
	});

在 filters.php 中添加过滤器

Route::filter('auth', function()
{
	if (Auth::guest()) {
		return Redirect::to('/login.html');
	}
	try {
		\Volicon\Acl\AclRoute::validateRoute();
	} catch (\Volicon\Acl\Exceptions\NoPermissionsException $ex) {
		return Response::make (json_encode($ex->getMessage()), 403);
	}
});

##Api Boolean Acl::check($resource, array $ids = []); // [] 是可选的，资源 ids。//check() 返回布尔值，可以执行资源的所有 ids 的操作。//如果 check($resource) 没有使用 [], 则当 $resource 未被阻止时返回 true。

Array Acl::filter($resource, array $ids = []) // 从 $ids [] 中返回授权的 id 数组。Volicon\Acl\AclPermission Acl::getPermission($resource) // 返回资源的权限。权限是一个具有参数：资源、值和允许的对象。

void Acl::registerHook($resource, $callback) void Acl::reguard() // 使用 acl 检查权限。void Acl::unguard() // 移除 acl 安全检查 Boolean Acl::isGuard() Volicon\Acl\RoleProviders\AclRoleProvider Acl::getRoleProvider($role_type) // 返回 '角色提供者' 实例。array Acl::getRoleProvidersTypes() // ids 数组 Illuminate\Support\Collection Acl::getRoles($roleIds = []) // ($roleIds 可选)，返回所有角色或数组中的角色。Volicon\Acl\AclUser Acl::getAuthUser() // 返回已登录的用户。

##AclUser

@property int user_id
@property int role_id
@property array roles // 分配给此用户的所有角色的 id。
@property array user_types
AclUser AclUser::find(id) // 返回一个用户。AclUser AclUser::findWithPermissions(id) // 返回具有用户权限数组的用户。void $aclUser->setRoles(array $ids = []) // 将 1 个或多个角色设置为用户，之前的角色将被移除。

AclUser 实现上述的 check、filter、getPermission 方法。通过 AclUser 权限时不会通过钩子，因此返回的数据库结果可能与现实不同。

##AclRole

@property int $role_id
@property string $name
@property int $type
@property bool $default 防止删除角色或更改其名称
@property Collection $permissions
@property Collection $users users ID's

方法

$acRole->getPermission
$acRole->add() // 将 $acRole 添加到数据库。
$acRole->update() // 将 $acRole 保存到数据库。
$acRole->remove // 从数据库中删除 $acRole。

与模型一起使用：从 Volicon\Acl\Models\AclModel 继承将自动检查权限。AclModel 监听 laravel 事件并检查添加、删除和更新的权限。对于选择事件，AclModel 将在查询中添加 'where'。

通过 API 添加角色：#示例

//Example 1:
$role = new AclRole();
$role->name = 'Users';
$role->permissions = [
	[
		'resource' => 'products.view',
		'values' => [],
		'allow' => true
	]
]
$role->users = [1,2];
$role->add(); 

//Example 2:
$role = new AclRole([
	'name' => 'product managers',
	'permissions' => [
		new AclPermission('products.manage',[],true)
	]
]);
$role->add();

$user = User::create(['username' => 'laravel', 'password' => 'strong']);
$aclUser = new AclUser($user);
$aclUser->setRoles(3);

AclModel 示例

use Volicon\Acl\Models\AclMode as Eloquent;

class Product extends Eloquent {
	protected $acl_field_key = 'product_id'; // if not defined use primary key
	
}

$products = Product::where('category', '=', 'good')->get(); //Acl add where depend of the permission of the resource Product.select

volicon / laravel-acl

维护者

详细信息

README