Updated docs

Signed-off-by: Eric Richer [email protected] <[email protected]>

docs/docs/gettingstarted.md → docs/docs/quick-start.md

@@ -1,8 +1,54 @@
 ---
-sidebar_label: Getting Started
-sidebar_position: 2
-title: Getting started
+title: Quick Start
+sidebar_position: 1
 ---
+
+LmcRbac offers components and services to implement role-based access control (RBAC) in your application.
+LmcRbac extends the components provided by [laminas-permissions-rbac](https://github.com/laminas/laminas-permissions-rbac).
+
+LmcRbac can be used in Laminas MVC and in Mezzio applications.
+
+:::tip
+If you are upgrading from LmcRbac v1 or from zfc-rbac v3, please read the [Upgrading section](Upgrading/to-v2.md)
+:::
+
+## Concepts
+
+[Role-Based Access Control (RBAC)](https://en.wikipedia.org/wiki/Role-based_access_control)
+is an approach to restricting system access to authorized users by putting emphasis
+on roles and their permissions.
+
+In the RBAC model:
+
+- an **identity** has one of more roles.
+- a **role** has one of more permissions.
+- a **permission** is typically an action like "read", "write", "delete".
+- a **role** can have **child roles** thus providing a hierarchy of roles where a role will inherit the permissions of all its child roles.
+
+### Authorization
+
+An identity will be authorized to perform an action, such as accessing a resource, if it is granted
+the permission that controls the execution of the action.
+
+For example, deleting an item could be restricted to identities that have at least one role that has the
+`item.delete` permission.  This could be implemented by defining a `member` role that has the `item.delete` and assigning
+this role of an authenticated user.
+
+### Dynamic Assertions
+
+In some cases, just checking if the identity has the `item.delete` permission is not enough.
+It would also be necessary to check, for example, that the `item` belongs to the identity. Dynamic assertion allow
+to specify some extra checks before granting access to perform an action such as, in this case, being the owner of the
+resource.
+
+### Identities
+
+An identity is typically provided by an authentication process within the application.
+
+Authentication is not in the scope of `LmcRbac` and it is assumed that an identity entity that can provide the assigned
+roles is available when using the authorization service. If no identity is available, as it would be the case when no
+user is "logged in", then a guest role is assumed.
+
 ## Requirements
 
 - PHP 8.1 or higher
@@ -22,7 +68,7 @@ You will be prompted by the `laminas-component-installer` plugin to inject LM-Co
 :::note
 **Manual installation:**
 
-Enable the module by adding `LmcRbac` key to your `application.config.php` or `modules.config.php` file for Laminas MVC 
+Enable the module by adding `LmcRbac` key to your `application.config.php` or `modules.config.php` file for Laminas MVC
 applications, or to the `config/config.php` file for Mezzio applications.
 :::
 

docs/docusaurus.config.js

@@ -9,7 +9,7 @@ import {themes as prismThemes} from 'prism-react-renderer';
 /** @type {import('@docusaurus/types').Config} */
 const config = {
     title: 'LmcRbac',
-    tagline: 'Role-based access control components for your Laminas or Mezzio application',
+    tagline: 'Role-based access control components for your Laminas MVC and Mezzio application',
     favicon: 'img/favicon.ico',
 
   // Set the production url of your site here
@@ -102,6 +102,7 @@ themeConfig:
         footer: {
             style: 'dark',
             links: [
+/*
             {
                 title: 'Docs',
                 items: [
@@ -111,6 +112,8 @@ themeConfig:
                 },
                 ],
             },
+
+ */
             {
                 title: 'Community',
                 items: [
@@ -123,10 +126,13 @@ themeConfig:
             {
                 title: 'More',
                 items: [
+/*
                 {
                     label: 'Blog',
                     to: '/blog',
                 },
+
+ */
                 {
                     label: 'GitHub',
                     href: 'https://github.com/lm-commons/lmcrbac',

docs/src/components/HomepageFeatures/index.js

@@ -57,15 +57,9 @@ export default function HomepageFeatures() {
         <div className={clsx("row")}>
             <div className={clsx("col col--8")}>
                 <Heading as="h1">Introduction</Heading>
-                <p>Components and services to provide role-based access control (RBAC) to your application.</p>
+                <p>LmcRbac offers components and services to implement role-based access control (RBAC) in your
+                    application. LmcRbac extends the components provided by <Link href="https://docs.laminas.dev/laminas-permissions-rbac">laminas-permissions-rbac</Link>.</p>
                 <p>LmcRbac can be used in Laminas MVC and in Mezzio applications.</p>
-                <p>Based on the original work of <a
-                    href="https://github.com/ZF-Commons/zfc-rbac">ZF-Commons/zfc-rbac</a> v3.x.</p>
-                <p>If you are looking for the Laminas version of zfc-rbac v2, please use <a
-                    href="https://github.com/LM-Commons/LmcRbacMvc">LM-Commons/LmcRbacMvc</a>.</p>
-                <div className={styles.buttons}>
-                    <Link className="button buttton--primary" to="/docs/gettingstarted">Get started</Link>
-                </div>
                 <Heading as="h2">Support</Heading>
                 <ul>
                     <li>File issues at <a

docs/src/components/HomepageHeader/index.js

@@ -0,0 +1,26 @@
+import clsx from "clsx";
+import styles from "../../pages/index.module.css";
+import Heading from "@theme/Heading";
+import useDocusaurusContext from "@docusaurus/core/lib/client/exports/useDocusaurusContext";
+import Link from "@docusaurus/core/lib/client/exports/Link";
+
+export function HomepageHeader() {
+    const {siteConfig} = useDocusaurusContext();
+    return (
+        <header className={clsx('hero hero--primary', styles.heroBanner)}>
+            <div className="container">
+                <Heading as="h1" className="hero__title">
+                    {siteConfig.title}
+                </Heading>
+                <p className="hero__subtitle">{siteConfig.tagline}</p>
+                <div className={styles.buttons}>
+                    <Link
+                        className="button button--secondary button--lg"
+                        to="/docs/next/quick-start">
+                        Quick start
+                    </Link>
+                </div>
+            </div>
+        </header>
+    );
+}

docs/src/pages/index.js

@@ -2,38 +2,15 @@ import clsx from 'clsx';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Layout from '@theme/Layout';
 import HomepageFeatures from '@site/src/components/HomepageFeatures';
+import {HomepageHeader} from "../components/HomepageHeader";
 
-import Heading from '@theme/Heading';
-import styles from './index.module.css';
 
-function HomepageHeader() {
-  const {siteConfig} = useDocusaurusContext();
-  return (
-    <header className={clsx('hero hero--primary', styles.heroBanner)}>
-      <div className="container">
-        <Heading as="h1" className="hero__title">
-          {siteConfig.title}
-        </Heading>
-        <p className="hero__subtitle">{siteConfig.tagline}</p>
-          {/*}
-        <div className={styles.buttons}>
-          <Link
-            className="button button--secondary button--lg"
-            to="/docs/intro">
-            Docusaurus Tutorial - 5min ⏱️
-          </Link>
-        </div>
-        {*/}
-      </div>
-    </header>
-  );
-}
 
 export default function Home() {
   const {siteConfig} = useDocusaurusContext();
   return (
     <Layout
-      title={`LM-Commons LmcRbac`}
+      title={siteConfig.title}
       description="Role based access controls for Laminas and Mezzio">
       <HomepageHeader />
       <main>

phpcs.xml

@@ -14,6 +14,7 @@
     <file>config</file>
     <file>src</file>
     <file>test</file>
+    <exclude-pattern>docs/*</exclude-pattern>
 
     <!-- Include all rules from the Laminas Coding Standard -->
     <rule ref="LaminasCodingStandard"/>