Merge pull request #45 from visto9259/3_docs

Moving documenation to Docusaurus built GitHub pages

.github/workflows/deploy-gh-pages.yml

@@ -0,0 +1,44 @@
+name: Build and Deploy to GitHub Pages
+
+defaults:
+  run:
+    shell: bash
+    working-directory: ./docs
+
+on:
+  push:
+    paths:
+      - 'docs/**'
+
+jobs:
+  deploy:
+    name: Build and Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./docs
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: yarn
+          cache-dependency-path: docs/yarn.lock
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+      - name: Build website
+        run: yarn build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Build output to publish to the `gh-pages` branch:
+          publish_dir: ./docs/build
+          # The following lines assign commit authorship to the official
+          # GH-Actions bot for deploys to `gh-pages` branch:
+          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
+          # The GH actions bot is used by default if you didn't specify the two fields.
+          # You can swap them out with your own user credentials.
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com

.github/workflows/test-deploy-gh-pages.yml

@@ -0,0 +1,29 @@
+name: Build GitHub Pages on PRs No Deploy
+
+defaults:
+  run:
+    shell: bash
+    working-directory: ./docs
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+
+jobs:
+  test-deploy:
+    name: Build GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: yarn
+          cache-dependency-path: docs/yarn.lock
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+      - name: Test build website
+        run: yarn build

README.md

@@ -57,7 +57,7 @@ the `lmc_rbac.global.php.dist` file to your `config/autoload` folder.
 
 ## Documentation
 
-The official documentation is available in the [/docs](/docs) folder.
+The official documentation is available [here](https://lm-commons.github.io/lmc-rbac-mvc).
 
 You can also find some Doctrine entities in the [/data](/data) folder that will help you to more quickly take advantage
 of LmcRbac.

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+node_modules
+
+# Production
+build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -1,48 +1,41 @@
-Welcome to the official LmcRbacMvc documentation. This documentation will help you quickly understand how to use
-and extend LmcRbacMvc.
-
-If you are looking for some information that is not listed in the documentation, please open an issue!
-
-1. [Introduction](01.%20Introduction.md)
-   1. [Why should I use an authorization module?](01.%20Introduction.md#why-should-i-use-an-authorization-module)
-   2. [What is the Rbac model?](01.%20Introduction.md#what-is-the-rbac-model)
-   3. [How can I integrate LmcRbacMvc into my application?](01.%20Introduction.md#how-can-i-integrate-lmcrbacmvc-into-my-application)
-
-2. [Quick Start](02.%20Quick%20Start.md)
-   1. [Specifying an identity provider](02.%20Quick%20Start.md#specifying-an-identity-provider)
-   2. [Adding a guard](02.%20Quick%20Start.md#adding-a-guard)
-   3. [Adding a role provider](02.%20Quick%20Start.md#adding-a-role-provider)
-   5. [Registering a strategy](02.%20Quick%20Start.md#registering-a-strategy)
-   6. [Using the authorization service](02.%20Quick%20Start.md#using-the-authorization-service)
-
-3. [Role providers](03.%20Role%20providers.md)
-   1. [What are role providers?](03.%20Role%20providers.md#what-are-role-providers)
-   2. [Identity providers](03.%20Role%20providers.md#identity-providers)
-   3. [Built-in role providers](03.%20Role%20providers.md#built-in-role-providers)
-   4. [Creating custom role providers](03.%20Role%20providers.md#creating-custom-role-providers)
-
-4. [Guards](04.%20Guards.md)
-   1. [What are guards and when to use them?](04.%20Guards.md#what-are-guards-and-when-should-you-use-them)
-   2. [Built-in guards](04.%20Guards.md#built-in-guards)
-   3. [Creating custom guards](04.%20Guards.md#creating-custom-guards)
-
-5. [Strategies](05.%20Strategies.md)
-   1. [What are strategies?](05.%20Strategies.md#what-are-strategies)
-   2. [Built-in strategies](05.%20Strategies.md#built-in-strategies)
-   3. [Creating custom strategies](05.%20Strategies.md#creating-custom-strategies)
-
-6. [Using the Authorization Service](06.%20Using%20the%20Authorization%20Service.md)
-   1. [Injecting the AuthorizationService](06.%20Using%20the%20Authorization%20Service.md#injecting-the-authorization-service)
-   2. [Checking permissions](06.%20Using%20the%20Authorization%20Service.md#checking-permissions-in-a-service)
-       1. [In a service](06.%20Using%20the%20Authorization%20Service.md#checking-permissions-in-a-service)
-       2. [In a controller's action using the isGranted controller plugin](06.%20Using%20the%20Authorization%20Service.md#in-a-controller-)
-       3. [In a view using the isGranted view helper](06.%20Using%20the%20Authorization%20Service.md#in-a-view-)
-   3. [Permissions and Assertions](06.%20Using%20the%20Authorization%20Service.md#permissions-and-assertions)
-
-7. [Cookbook](07.%20Cookbook.md)
-   1. [A real world example](07.%20Cookbook.md#a-real-world-application)
-   2. [Best practices](07.%20Cookbook.md#best-practices)
-   3. [Using LmcRbacMvc with Doctrine ORM](07.%20Cookbook.md#using-lmcrbacmvc-with-doctrine-orm)
-   4. [How to deal with roles with lot of permissions?](07.%20Cookbook.md#how-to-deal-with-roles-with-lot-of-permissions)
-   5. [Using LmcRbacMvc and ZF2 Assetic](07.%20Cookbook.md#using-lmcrbacmvc-and-zf2-assetic)
-   6. [Using LmcRbacMvc and LmcUser](07.%20Cookbook.md#using-lmcrbacmvc-and-lmcuser)
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/blog/2022-08-02-welcome.md

@@ -0,0 +1,10 @@
+---
+slug: welcome
+title: Welcome
+authors: [ericr]
+tags: [laminas, PHP]
+---
+Welcome to the new documentation website for the LM-Commons organization.
+
+This site is work in progress and the intent is obviously to keep it current with updates to the LM-Commons packages.
+

docs/blog/2024-02-22-New-documentation.md

@@ -0,0 +1,9 @@
+---
+slug: new-documentation
+title: New documentation
+authors: [ericr]
+tags: [laminas, PHP, lmcrbacmvc]
+---
+This the new documentation site dedicated to the LmcRbacMvc module.
+
+There are no changes to the code, just improvements in the documentation.

docs/blog/authors.yml

@@ -0,0 +1,5 @@
+ericr:
+  name: Eric Richer
+  title: LM-Commons Administrator
+  url: https://github.com/visto9259
+  image_url: https://github.com/visto9259.png

docs/07. Cookbook.md → docs/docs/cookbook.md

@@ -1,18 +1,11 @@
+---
+sidebar_position: 8
+---
 # Cookbook
 
 This section will help you further understand how LmcRbacMvc works by providing more concrete examples. If you have
 any other recipe you'd like to add, please open an issue!
 
-- [A Real World Application](07.%20Cookbook.md#a-real-world-application)
-    - [When to use Guards](07.%20Cookbook.md#when-using-guards-then)
-- [A Real World Application Part 2 - Only delete your own Posts](07.%20Cookbook.md#a-real-world-application-part-2---only-delete-your-own-posts)
-- [A Real World Application Part 3 - But Admins can delete everything](07.%20Cookbook.md#a-real-world-application-part-3---admins-can-delete-everything)
-- [A Real World Application Part 4 - Only admins have the menu item for managing the posts](07.%20Cookbook.md#user-content-a-real-world-application-part-4---checking-permissions-in-the-view)
-- [Using LmcRbacMvc with Doctrine ORM](07.%20Cookbook.md#using-lmcrbac-with-doctrine-orm)
-    - [How to deal with roles with lot of permissions?](07.%20Cookbook.md#how-to-deal-with-roles-with-lot-of-permissions)
-- [Using LmcRbacMvc and ZF2 Assetic](07.%20Cookbook.md#using-lmcrbacmvc-and-zf2-assetic)
-- [Using LmcRbacMvc and LmcUser](07.%20Cookbook.md#using-lmcrbacmvc-and-lmcuser)
-
 ## A Real World Application
 
 In this example we are going to create a very little real world application. We will create a controller
@@ -326,7 +319,7 @@ As we can see, we check within our Service if the User of our Application is all
 against the `deletePost` permission. Now how can we achieve that only a user who is the owner of the Post to be able to
 delete his own post, but other users can't? We do not want to change our Service with more complex logic because this
 is not the task of such service. The Permission-System should handle this. And we can, for this we have the
- [`AssertionPluginManager`](/LmcRbacMvc/Assertion/AssertionPluginManager.php) and here is how to do it:
+ `AssertionPluginManager` and here is how to do it:
 
 First of all we need to write an Assertion. The Assertion will return a boolean statement about the current
 identity being the owner of the post.
@@ -661,7 +654,7 @@ class HierarchicalRole implements HierarchicalRoleInterface
 
 And the last step is to create a Permission entity class which is a very simple entity class. You don't have to do specific things!
 
-You can find all entity examples in this folder : [Example](/data)
+You can find all entity examples in this folder : [Example](https://github.com/LM-Commons/LmcRbacMvc/tree/master/data)
 
 You need one more configuration step. Indeed, how can the RoleProvider retrieve your role and permissions? For this you need to configure `LmcRbacMvc\Role\ObjectRepositoryRoleProvider` in your `lmc_rbac.global.php` file :
 ```php
@@ -772,8 +765,3 @@ return [
     ]
 ];
 ```
-
-### Navigation
-
-* Back to [the Using the Authorization Service](06.%20Using%20the%20Authorization%20Service.md)
-* Back to [the Index](README.md)

docs/04. Guards.md → docs/docs/guards.md

@@ -1,3 +1,6 @@
+---
+sidebar_position: 5
+---
 # Guards
 
 In this section, you will learn:
@@ -13,11 +16,11 @@ the MVC workflow. They allow your application to quickly mark a request as unaut
 
 Here is a simple workflow without guards:
 
-![Zend Framework workflow without guards](images/workflow-without-guards.png?raw=true)
+![Laminas Framework workflow without guards](images/workflow-without-guards.png?raw=true)
 
 And here is a simple workflow with a route guard:
 
-![Zend Framework workflow with guards](images/workflow-with-guards.png?raw=true)
+![Laminas Framework workflow with guards](images/workflow-with-guards.png?raw=true)
 
 RouteGuard and ControllerGuard are not aware of permissions but rather only think about "roles". For
 instance, you may want to refuse access to each routes that begin by "admin/*" to all users that do not have the
@@ -38,7 +41,7 @@ that is not specified in the rules will be "granted" by default. Therefore, the
 mechanism.
 
 However, you may want a more restrictive approach (also called "whitelist"). In this mode, once a guard is added,
-anything that is not explicitely added will be refused by default.
+anything that is not explicitly added will be refused by default.
 
 For instance, let's say you have two routes: "index" and "login". If you specify a route guard rule to allow "index"
 route to "member" role, your "login" route will become defacto unauthorized to anyone, unless you add a new rule for
@@ -80,7 +83,7 @@ return [
 ];
 ```
 
-Because of the way Zend Framework 2 handles config, you can without problem define some rules in one module, and
+Because of the way Laminas Framework handles config, you can without problem define some rules in one module, and
 more rules in another module. All the rules will be automatically merged.
 
 > For your mental health, I recommend you to use either the route guard OR the controller guard, but not both. If
@@ -473,9 +476,3 @@ return [
 ];
 ```
 The array of IP addresses will be passed to `IpGuardFactory::__invoke` in the `$options` parameter.
-
-### Navigation
-
-* Continue to [the **Strategies**](05.%20Strategies.md)
-* Back to [the Role providers](03.%20Role%20providers.md)
-* Back to [the Index](README.md)

docs/docs/installation.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 2
+sidebar_label: Requirements and Installation
+---
+# Requirements and Installation
+## Requirements
+
+- PHP 7.4 or higher
+- [Zf-fr/Rbac component v1](https://github.com/zf-fr/rbac): this is actually a prototype for the ZF3 Rbac component.
+- [Laminas Components 2.x | 3.x or higher](http://www.github.com/laminas)
+
+
+## Optional
+
+- [DoctrineModule](https://github.com/doctrine/DoctrineModule): if you want to use some built-in role and permission providers.
+- [Laminas\DeveloperTools](https://github.com/laminas/Laminas\DeveloperTools): if you want to have useful stats added to
+  the Laminas Developer toolbar.
+
+
+## Installation
+
+LmcRbacMvc only officially supports installation through Composer. For Composer documentation, please refer to
+[getcomposer.org](http://getcomposer.org/).
+
+Install the module:
+
+```sh
+$ composer require lm-commons/lmc-rbac-mvc:^3.0
+```
+
+Enable the module by adding `LmcRbacMvc` key to your `application.config.php` or `modules.config.php` file. Customize the module by copy-pasting
+the `lmc_rbac.global.php.dist` file to your `config/autoload` folder.
+
+## Upgrade
+
+LmcRbacMvc introduces breaking changes from zfcrbac v2:
+- [BC] The namespace has been changed from `ZfcRbac` to `LmcRbacMvc`.
+- [BC] The key `zfc_rbac` in autoload and module config files has been replaced
+  by the `lmc_rbac` key.
+- Requires PHP 7.4 or later
+- Requires Laminas MVC components 3.x or later
+- Uses PSR-4 autoload