Merge pull request #325 from cakephp/docs-update-3x

Update documentation for CakePHP 5 / PHP 8+ compatibility

Author: dereuromark

docs/en/component.rst

@@ -8,7 +8,7 @@ requires use of the Middleware, so make sure it is applied as well. To use the
 component, first load it::
 
     // In your AppController
-    public function initialize()
+    public function initialize(): void
     {
         parent::initialize();
         $this->loadComponent('Authorization.Authorization');

docs/en/index.rst

@@ -22,7 +22,7 @@ Getting Started
 ===============
 
 The Authorization plugin integrates into your application as a middleware layer
-and optionally a component to make checking authorization easier. First, lets
+and optionally a component to make checking authorization easier. First, let's
 apply the middleware. In **src/Application.php** add the following to the class
 imports::
 
@@ -31,7 +31,6 @@ imports::
     use Authorization\AuthorizationServiceProviderInterface;
     use Authorization\Middleware\AuthorizationMiddleware;
     use Authorization\Policy\OrmResolver;
-    use Psr\Http\Message\ResponseInterface;
     use Psr\Http\Message\ServerRequestInterface;
 
 Add the ``AuthorizationServiceProviderInterface`` to the implemented interfaces
@@ -56,7 +55,7 @@ Then make your application's ``middleware()`` method look like::
             // and authentication middleware.
             ->add(new AuthorizationMiddleware($this));
 
-        return $middlewareQueue();
+        return $middlewareQueue;
     }
 
 The placement of the ``AuthorizationMiddleware`` is important and must be added
@@ -78,7 +77,7 @@ define the ``AuthorizationService`` it wants to use. Add the following method yo
 This configures basic :doc:`/policy-resolvers` that will match
 ORM entities with their policy classes.
 
-Next, lets add the ``AuthorizationComponent`` to ``AppController``. In
+Next, let's add the ``AuthorizationComponent`` to ``AppController``. In
 **src/Controller/AppController.php** add the following to the ``initialize()``
 method::
 
@@ -89,7 +88,7 @@ authorization on a per-action basis more easily. For example, we can do::
 
     public function edit($id = null)
     {
-        $article = $this->Article->get($id);
+        $article = $this->Articles->get($id);
         $this->Authorization->authorize($article, 'update');
 
         // Rest of action

docs/en/middleware.rst

@@ -24,14 +24,14 @@ A basic example would be::
 
     class Application extends BaseApplication implements AuthorizationServiceProviderInterface
     {
-        public function getAuthorizationService(ServerRequestInterface $request, ResponseInterface $response)
+        public function getAuthorizationService(ServerRequestInterface $request): AuthorizationServiceInterface
         {
             $resolver = new OrmResolver();
 
             return new AuthorizationService($resolver);
         }
 
-        public function middleware($middlewareQueue)
+        public function middleware(MiddlewareQueue $middlewareQueue): MiddlewareQueue
         {
             // other middleware
             $middlewareQueue->add(new AuthorizationMiddleware($this));
@@ -114,7 +114,7 @@ implementing the ``Authorization\IdentityInterface`` and using the
         /**
          * Setter to be used by the middleware.
          */
-        public function setAuthorization(AuthorizationServiceInterface $service)
+        public function setAuthorization(AuthorizationServiceInterface $service): static
         {
             $this->authorization = $service;
 
@@ -150,10 +150,8 @@ If you also use the Authentication plugin make sure to implement both interfaces
 
         /**
          * Authentication\IdentityInterface method
-         *
-         * @return string
          */
-        public function getIdentifier()
+        public function getIdentifier(): int|string|null
         {
             return $this->id;
         }
@@ -254,7 +252,7 @@ How to create a custom UnauthorizedHandler
 #. Create this file ``src/Middleware/UnauthorizedHandler/CustomRedirectHandler.php``::
 
     <?php
-    declare( strict_types = 1 );
+    declare(strict_types=1);
 
     namespace App\Middleware\UnauthorizedHandler;
 

docs/en/policies.rst

@@ -46,19 +46,19 @@ You can generate empty policy classes for ORM objects using ``bake``:
 Writing Policy Methods
 ======================
 
-The policy class we just created doesn't do much right now. Lets define a method
+The policy class we just created doesn't do much right now. Let's define a method
 that allows us to check if a user can update an article::
 
-    public function canEdit(IdentityInterface $user, Article $article)
+    public function canEdit(IdentityInterface $user, Article $article): bool
     {
-        return $user->id == $article->user_id;
+        return $user->id === $article->user_id;
     }
 
 Policy methods must return ``true`` or a ``Result`` objects to indicate success.
 All other values will be interpreted as failure.
 
 Policy methods will receive ``null`` for the ``$user`` parameter when handling
-unauthencticated users. If you want to automatically fail policy methods for
+unauthenticated users. If you want to automatically fail policy methods for
 anonymous users you can use the ``IdentityInterface`` typehint.
 
 .. _policy-result-objects:
@@ -72,9 +72,9 @@ passed/failed::
 
    use Authorization\Policy\Result;
 
-   public function canUpdate(IdentityInterface $user, Article $article)
+   public function canUpdate(IdentityInterface $user, Article $article): Result
    {
-       if ($user->id == $article->user_id) {
+       if ($user->id === $article->user_id) {
            return new Result(true);
        }
        // Results let you define a 'reason' for the failure.

docs/en/policy-resolvers.rst

@@ -76,7 +76,7 @@ The OrmResolver supports customization through its constructor::
     $overrides = [
         'Blog' => 'Cms',
     ];
-    $resolver = new OrmResolver($appNamespace, $overrides)
+    $resolver = new OrmResolver($appNamespace, $overrides);
 
 Using Multiple Resolvers
 ========================

docs/en/request-authorization-middleware.rst

@@ -56,8 +56,6 @@ Next, map the request class to the policy inside
     use Authorization\Middleware\AuthorizationMiddleware;
     use Authorization\Middleware\RequestAuthorizationMiddleware;
     use Authorization\Policy\MapResolver;
-    use Authorization\Policy\OrmResolver;
-    use Psr\Http\Message\ResponseInterface;
     use Cake\Http\ServerRequest;
 
 
@@ -77,6 +75,8 @@ AuthorizationMiddleware::
         // Add authorization (after authentication if you are using that plugin too).
         $middlewareQueue->add(new AuthorizationMiddleware($this));
         $middlewareQueue->add(new RequestAuthorizationMiddleware());
+
+        return $middlewareQueue;
     }
 
 Controller Usage