If `$identity` is null, then the `guest` is used.
The `guest` role is definable via configuration and defaults to `'guest'`. | +| `$permission` | The permission to check against | +| `$context` | A context that will be passed to dynamic assertions that are defined for the permission | + +More on dynamic assertions can be found in the [Assertions](assertions.md) section. + +More on the `guest` role can be found in the [Configuration](configuration.md) section. + diff --git a/docs/docs/concepts.md b/docs/versioned_docs/version-1.4/concepts.md similarity index 100% rename from docs/docs/concepts.md rename to docs/versioned_docs/version-1.4/concepts.md diff --git a/docs/versioned_docs/version-1.4/configuration.md b/docs/versioned_docs/version-1.4/configuration.md new file mode 100644 index 0000000..9c1d32d --- /dev/null +++ b/docs/versioned_docs/version-1.4/configuration.md @@ -0,0 +1,18 @@ +--- +sidebar_label: Configuration +sidebar_position: 7 +title: Configuring LmcRbac +--- + +LmcRbac is configured via the `lmc_rbac` key in the application config. + +This is typically achieved by creating +a `config/autoload/lmcrbac.global.php` file. A sample configuration file is provided in the `config/` folder. + +## Reference + +| Key | Description | +|--|------------------------------------------------------------------------------------------------------------------------------------------------| +| `guest_role` | Defines the name of the `guest` role when no identity exists.
Defaults to `'guest'`. | +| `assertion_map` | Defines the dynamic assertions that are associated to permissions.
Defaults to `[]`.
See the [Dynamic Assertions](assertions) section. | +| `role_provider` | Defines the role provider.
Defaults to `[]`
See the [Role Providers](role-providers) section. | diff --git a/docs/docs/gettingstarted.md b/docs/versioned_docs/version-1.4/gettingstarted.md similarity index 100% rename from docs/docs/gettingstarted.md rename to docs/versioned_docs/version-1.4/gettingstarted.md diff --git a/docs/docs/migration.md b/docs/versioned_docs/version-1.4/migration.md similarity index 100% rename from docs/docs/migration.md rename to docs/versioned_docs/version-1.4/migration.md diff --git a/docs/docs/quickstart.md b/docs/versioned_docs/version-1.4/quickstart.md similarity index 100% rename from docs/docs/quickstart.md rename to docs/versioned_docs/version-1.4/quickstart.md diff --git a/docs/versioned_docs/version-1.4/role-providers.md b/docs/versioned_docs/version-1.4/role-providers.md new file mode 100644 index 0000000..a65654e --- /dev/null +++ b/docs/versioned_docs/version-1.4/role-providers.md @@ -0,0 +1,193 @@ +--- +sidebar_label: Roles and Role providers +title: Roles and Role providers +sidebar_position: 4 +--- + +## Role types + +A role is an object that returns a list of permissions that the role has. + +`LmcRbac` support two types of roles: hierarchical roles and flat roles. + +### Flat roles + +A flat role is the simplest role object. It contains the list of permissions that +the role has. + +Flat roles are defined using by the `LmcRbac\Role\Role` class or by classes +implementing the `LmcRbac\Role\RoleInterface`. + +### Hierarchical roles + +A hierarchical role is a role that has child roles and therefore provides +a hierarchy of roles where a role inherit the permissions of all its child roles. + +For example, a 'user' role may have the 'read' and 'write' permissions, and a 'admin' role +may inherit the permissions of the 'user' role plus an additional 'delete' role. In this structure, +the 'admin' role will have 'user' as its child role. + +Hierarchical roles may have flat roles or hierarchical roles as children. + +Hierarchical roles are defined using by the `LmcRbac\Role\HierarchicalRole` class or by classes +implementing the `LmcRbac\Role\HierarchicalRoleInterface`. + +## Role Providers +A role provider is an object that returns a list of roles. A role provider must implement the +`LmcRbac\Role\RoleProviderInterface` interface. The only required method is `getRoles`, and must return an array +of `LmcRbac\Role\RoleInterface` objects. + +Roles can come from one of many sources: in memory, from a file, from a database, etc. However, you can specify only one role provider per application. + +### Built-in role providers + +LmcRbac comes with two built-in role providers: `LmcRbac\Role\InMemoryRoleProvider` and `LmcRbac\Role\ObjectRepositoryRoleProvider`. A role +provider must be added to the `role_provider` subkey in the configuration file: + +```php +return [ + 'lmc_rbac' => [ + 'role_provider' => [ + // Role provider config here! + ] + ] +]; +``` + +### `LmcRbac\Role\InMemoryRoleProvider` + +This provider is ideal for small/medium sites with few roles/permissions. All the data is specified in a simple associative array in a +PHP file. + +Here is an example of the format you need to use: + +```php +return [ + 'lmc_rbac' => [ + 'role_provider' => [ + 'LmcRbac\Role\InMemoryRoleProvider' => [ + 'admin' => [ + 'children' => ['member'], + 'permissions' => ['article.delete'] + ], + 'member' => [ + 'children' => ['guest'], + 'permissions' => ['article.edit', 'article.archive'] + ], + 'guest' => [ + 'permissions' => ['article.read'] + ], + ], + ], + ], +]; +``` + +The `children` and `permissions` subkeys are entirely optional. Internally, the `LmcRbac\Role\InMemoryRoleProvider` creates +either a `LmcRbac\Role\Role` object if the role does not have any children, or a `LmcRbac\Role\HierarchicalRole` if +the role has at least one child. + +If you are more confident with flat RBAC, the previous config can be re-written to remove any inheritence between roles: + +```php +return [ + 'lmc_rbac' => [ + 'role_provider' => [ + 'LmcRbac\Role\InMemoryRoleProvider' => [ + 'admin' => [ + 'permissions' => [ + 'article.delete', + 'article.edit', + 'article.archive', + 'article.read' + ] + ], + 'member' => [ + 'permissions' => [ + 'article.edit', + 'article.archive', + 'article.read' + ] + ], + 'guest' => [ + 'permissions' => ['article.read'] + ] + ] + ] + ] +]; +``` + +### `LmcRbac\Role\ObjectRepositoryRoleProvider` + +This provider fetches roles from a database using `Doctrine\Common\Persistence\ObjectRepository` interface. + +You can configure this provider by giving an object repository service name that is fetched from the service manager +using the `object_repository` key: + +```php +return [ + 'lmc_rbac' => [ + 'role_provider' => [ + 'LmcRbac\Role\ObjectRepositoryRoleProvider' => [ + 'object_repository' => 'App\Repository\RoleRepository', + 'role_name_property' => 'name' + ], + ], + ], +]; +``` + +Or you can specify the `object_manager` and `class_name` options: + +```php +return [ + 'lmc_rbac' => [ + 'role_provider' => [ + 'LmcRbac\Role\ObjectRepositoryRoleProvider' => [ + 'object_manager' => 'doctrine.entitymanager.orm_default', + 'class_name' => 'App\Entity\Role', + 'role_name_property' => 'name' + ], + ], + ], +]; +``` + +In both cases, you need to specify the `role_name_property` value, which is the name of the entity's property +that holds the actual role name. This is used internally to only load the identity roles, instead of loading +the whole table every time. + +Please note that your entity fetched from the table MUST implement the `LmcRbac\Role\RoleInterface` interface. + +Sample ORM entity models are provided in the `/data` folder for flat role, hierarchical role and permission. + +## Creating custom role providers + +To create a custom role provider, you first need to create a class that implements the +`LmcRbac\Role\RoleProviderInterface` interface. + +Then, you need to add it to the role provider manager: + +```php +return [ + 'lmc_rbac' => [ + 'role_provider' => [ + 'Application\Role\CustomRoleProvider' => [ + // Options + ], + ], + ], +]; +``` +And the role provider is created using the service manager: +```php +return [ + 'service_manager' => [ + 'factories' => [ + 'Application\Role\CustomRoleProvider' => 'Application\Factory\CustomRoleProviderFactory' + ], + ], +]; +``` + diff --git a/docs/versioned_sidebars/version-1.4-sidebars.json b/docs/versioned_sidebars/version-1.4-sidebars.json new file mode 100644 index 0000000..5f41a72 --- /dev/null +++ b/docs/versioned_sidebars/version-1.4-sidebars.json @@ -0,0 +1,8 @@ +{ + "documentationSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/docs/versions.json b/docs/versions.json new file mode 100644 index 0000000..df2d553 --- /dev/null +++ b/docs/versions.json @@ -0,0 +1,3 @@ +[ + "1.4" +] diff --git a/docs/yarn.lock b/docs/yarn.lock index c6c1e9c..04f9823 100644 --- a/docs/yarn.lock +++ b/docs/yarn.lock @@ -1225,7 +1225,7 @@ "@docsearch/css" "3.6.1" algoliasearch "^4.19.1" -"@docusaurus/core@3.5.2", "@docusaurus/core@^3.4.0": +"@docusaurus/core@3.5.2", "@docusaurus/core@^3.5.2": version "3.5.2" resolved "https://registry.yarnpkg.com/@docusaurus/core/-/core-3.5.2.tgz#3adedb90e7b6104592f1231043bd6bf91680c39c" integrity sha512-4Z1WkhCSkX4KO0Fw5m/Vuc7Q3NxBG53NE5u59Rs96fWkMPZVSrzEPP16/Nk6cWb/shK7xXPndTmalJtw7twL/w== @@ -1347,7 +1347,7 @@ vfile "^6.0.1" webpack "^5.88.1" -"@docusaurus/module-type-aliases@3.5.2", "@docusaurus/module-type-aliases@^3.4.0": +"@docusaurus/module-type-aliases@3.5.2", "@docusaurus/module-type-aliases@^3.5.2": version "3.5.2" resolved "https://registry.yarnpkg.com/@docusaurus/module-type-aliases/-/module-type-aliases-3.5.2.tgz#4e8f9c0703e23b2e07ebfce96598ec83e4dd2a9e" integrity sha512-Z+Xu3+2rvKef/YKTMxZHsEXp1y92ac0ngjDiExRdqGTmEKtCUpkbNYH8v5eXo5Ls+dnW88n6WTa+Q54kLOkwPg== @@ -1479,7 +1479,7 @@ sitemap "^7.1.1" tslib "^2.6.0" -"@docusaurus/preset-classic@^3.4.0": +"@docusaurus/preset-classic@^3.5.2": version "3.5.2" resolved "https://registry.yarnpkg.com/@docusaurus/preset-classic/-/preset-classic-3.5.2.tgz#977f78510bbc556aa0539149eef960bb7ab52bd9" integrity sha512-3ihfXQ95aOHiLB5uCu+9PRy2gZCeSZoDcqpnDvf3B+sTrMvMTr8qRUzBvWkoIqc82yG5prCboRjk1SVILKx6sg== @@ -1577,7 +1577,7 @@ fs-extra "^11.1.1" tslib "^2.6.0" -"@docusaurus/types@3.5.2", "@docusaurus/types@^3.4.0": +"@docusaurus/types@3.5.2", "@docusaurus/types@^3.5.2": version "3.5.2" resolved "https://registry.yarnpkg.com/@docusaurus/types/-/types-3.5.2.tgz#058019dbeffbee2d412c3f72569e412a727f9608" integrity sha512-N6GntLXoLVUwkZw7zCxwy9QiuEXIcTVzA9AkmNw16oc0AP3SXLrMmDMMBIfgqwuKWa6Ox6epHol9kMtJqekACw== diff --git a/phpcs.xml b/phpcs.xml index 5fbe6d6..7813380 100644 --- a/phpcs.xml +++ b/phpcs.xml @@ -14,6 +14,7 @@