[skip ci][doc] Acl suite+router update

docs/controller/router.rst

@@ -312,7 +312,7 @@ It is possible to specify the http method or methods associated with a route:
 
          class ProductsController extends ControllerBase{
 
-            #[Route('products',methods: ['get'])]
+            #[Route('products',methods: ['get','post'])]
             public function index(){}
 
          }
@@ -329,7 +329,7 @@ It is possible to specify the http method or methods associated with a route:
          class ProductsController extends ControllerBase{
 
             /**
-             * @route("products","methods"=>["get"])
+             * @route("products","methods"=>["get","post"])
              */
             public function index(){}
 
@@ -349,14 +349,43 @@ There is a specific annotation for each of the existing HTTP methods:
  - **@head** => **Head**
  - **@options** => **Options**
 
-With annotations:
+.. tabs::
+
+   .. tab:: Attributes
+
+      .. code-block:: php
+         :linenos:
+         :caption: app/controllers/ProductsController.php
+         :emphasize-lines: 7
+
+         namespace controllers;
+
+         use Ubiquity\attributes\items\router\Get;
+
+         class ProductsController extends ControllerBase{
+
+            #[Get('products')]
+            public function index(){}
 
-``@get("products")``
+         }
+
+   .. tab:: Annotations
 
+      .. code-block:: php
+         :linenos:
+         :caption: app/controllers/ProductsController.php
+         :emphasize-lines: 6
 
-With attributes:
+         namespace controllers;
 
-``#[Get('products')]``
+         class ProductsController extends ControllerBase{
+
+            /**
+             * @get("products")
+             */
+            public function index(){}
+
+         }
 
 
 Route name

docs/security/acl.rst

@@ -65,7 +65,7 @@ The **AclManager** service can be started directly from the **webtools** interfa
     \Ubiquity\security\acl\AclManager::startWithCacheProvider();
 
 ACLCacheProvider
-****************
+----------------
 This default provider allows you to manage ACLs defined through attributes or annotations.
 
 AclController
@@ -182,3 +182,119 @@ Adding a Role ``@USER`` inheriting from ``@GUEST``.
    AclManager::addRole('@GUEST');
    AclManager::addRole('@USER',['@GUEST']);
 
+
+Strategies for defining ACLs
+============================
+
+With few resources:
+-------------------
+Defining authorisations for each controller's action or action group:
+
+Resources logically correspond to controllers, and permissions to actions.
+But this rule may not be respected, and an action may be defined as a resource, as required.
+
+The only mandatory rule is that a Controller/action pair can only correspond to one Resource/permission pair (not necessarily unique).
+
+
+.. code-block:: php
+   :caption: app/controllers/BaseAclController.php
+
+   namespace controllers;
+
+   use Ubiquity\controllers\Controller;
+   use Ubiquity\security\acl\controllers\AclControllerTrait;
+   use Ubiquity\attributes\items\acl\Permission;
+   use Ubiquity\attributes\items\acl\Resource;
+
+   #[Resource('Foo')]
+   #[Allow('@ADMIN')]
+   class FooController extends Controller {
+      use AclControllerTrait;
+
+      #[Allow('@NONE')]
+      public function index() {
+         echo 'index';
+      }
+
+      #[Allow('@USER')]
+      public function read() {
+         echo 'read';
+      }
+
+      #[Allow('@USER')]
+      public function write() {
+         echo 'write';
+      }
+
+      public function admin() {
+         echo 'admin';
+      }
+
+      public function _getRole() {
+         return $_GET['role']??'@NONE';
+      }
+
+      /**
+       * {@inheritdoc}
+       * @see \Ubiquity\controllers\Controller::onInvalidControl()
+       */
+      public function onInvalidControl() {
+         echo $this->_getRole() . ' is not allowed!';
+      }
+
+   }
+
+
+
+With more resources:
+--------------------
+
+
+.. code-block:: php
+   :caption: app/controllers/BaseAclController.php
+
+   namespace controllers;
+
+   use Ubiquity\controllers\Controller;
+   use Ubiquity\security\acl\controllers\AclControllerTrait;
+   use Ubiquity\attributes\items\acl\Permission;
+   use Ubiquity\attributes\items\acl\Resource;
+
+   #[Resource('Foo')]
+   class FooController extends Controller {
+      use AclControllerTrait;
+
+      #[Permission('INDEX',1)]
+      public function index() {
+         echo 'index';
+      }
+
+      #[Permission('READ',2)]
+      public function read() {
+         echo 'read';
+      }
+
+      #[Permission('WRITE',3)]
+      public function write() {
+         echo 'write';
+      }
+
+      #[Permission('ADMIN',10)]
+      public function admin() {
+         echo 'admin';
+      }
+
+      public function _getRole() {
+         return $_GET['role']??'NONE';
+      }
+
+      /**
+       * {@inheritdoc}
+       * @see \Ubiquity\controllers\Controller::onInvalidControl()
+       */
+      public function onInvalidControl() {
+         echo $this->_getRole() . ' is not allowed!';
+      }
+
+   }
+