Merge branch '1.1.x' into master

Author: markstory

.travis.yml

@@ -40,7 +40,7 @@ script:
   - if [[ $DEFAULT = 1 && $TRAVIS_PHP_VERSION != 7.3 ]]; then vendor/bin/phpunit; fi
 
   - if [[ $PHPCS = 1 ]]; then vendor/bin/phpcs -n -p --extensions=php --standard=vendor/cakephp/cakephp-codesniffer/CakePHP src/ tests/; fi
-  - if [[ $PHPSTAN = 1 ]]; then vendor/bin/phpstan analyse -l 4 src; fi
+  - if [[ $PHPSTAN = 1 ]]; then vendor/bin/phpstan analyse -c phpstan.neon -l 4 src; fi
 
 after_success:
   - if [[ $DEFAULT = 1 && $TRAVIS_PHP_VERSION = 7.3 ]]; then bash <(curl -s https://codecov.io/bash); fi

docs/Checking-Authorization.md

@@ -15,6 +15,17 @@ if ($user->can('delete', $article)) {
 }
 ```
 
+If your policies return [Result objects](../Policies.md#policy-result-objects) 
+be sure to check their status as  `can()` returns the result instance:
+
+```php
+// Assuming our policy returns a result.
+$result = $user->can('delete', $article);
+if ($result->getStatus()) {
+    // Do deletion
+}
+```
+
 You can also use the `identity` to apply scopes:
 
 ```php

docs/Policies.md

@@ -45,13 +45,31 @@ public function canUpdate(IdentityInterface $user, Article $article)
 }
 ```
 
-Policy methods must return `true` to indicate success. All other values will be
-interpreted as failure.
-
-Policy methods will get ``null`` for the ``$user`` parameter when handling
+Policy methods will receive ``null`` for the ``$user`` parameter when handling
 unauthencticated users. If you want to automatically fail policy methods for
 anonymous users you can use the `IdentityInterface` typehint.
 
+### Policy Result Objects
+
+In addition to booleans, policy methods can return ``Result`` objects which
+allow more context to be provided on why the policy passed/failed.
+
+```php
+use Authorization\Policy\Result;
+
+public function canUpdate(IdentityInterface $user, Article $article)
+{
+    if ($user->id == $article->user_id) {
+        return new Result(true);
+    }
+    // Results let you define a 'reason' for the failure.
+    return new Result(false, 'not-owner');
+}
+```
+
+Any return value that is not `true` or a `ResultInterface` object will be
+considered a failure.
+
 ### Policy Scopes
 
 In addition to policies being able to define pass/fail authorization checks,

phpstan.neon

@@ -0,0 +1,3 @@
+parameters:
+    ignoreErrors:
+        - '#Casting to [a-z]+ something that.s already [a-z]+.#'

src/AuthorizationService.php

@@ -17,6 +17,7 @@
 use Authorization\Policy\BeforePolicyInterface;
 use Authorization\Policy\Exception\MissingMethodException;
 use Authorization\Policy\ResolverInterface;
+use Authorization\Policy\ResultInterface;
 use RuntimeException;
 
 class AuthorizationService implements AuthorizationServiceInterface
@@ -55,17 +56,22 @@ public function can($user, $action, $resource)
         if ($policy instanceof BeforePolicyInterface) {
             $result = $policy->before($user, $resource, $action);
 
-            if (is_bool($result)) {
+            if ($result instanceof ResultInterface || is_bool($result)) {
                 return $result;
             }
             if ($result !== null) {
-                throw new RuntimeException('Pre-authorization check must return `bool` or `null`.');
+                $message = sprintf('Pre-authorization check must return `%s`, `bool` or `null`.', ResultInterface::class);
+                throw new RuntimeException($message);
             }
         }
 
         $handler = $this->getCanHandler($policy, $action);
         $result = $handler($user, $resource);
 
+        if ($result instanceof ResultInterface) {
+            return $result;
+        }
+
         return $result === true;
     }
 

src/AuthorizationServiceInterface.php

@@ -28,7 +28,7 @@ interface AuthorizationServiceInterface
      * @param \Authorization\IdentityInterface|null $user The user to check permissions for.
      * @param string $action The action/operation being performed.
      * @param mixed $resource The resource being operated on.
-     * @return bool
+     * @return bool|\Authorization\Policy\ResultInterface
      */
     public function can($user, $action, $resource);
 

src/Controller/Component/AuthorizationComponent.php

@@ -16,8 +16,9 @@
 
 use Authorization\AuthorizationServiceInterface;
 use Authorization\Exception\ForbiddenException;
-use Authorization\Exception\MissingIdentityException;
 use Authorization\IdentityInterface;
+use Authorization\Policy\Result;
+use Authorization\Policy\ResultInterface;
 use Cake\Controller\Component;
 use Cake\Http\ServerRequest;
 use InvalidArgumentException;
@@ -65,7 +66,11 @@ public function authorize($resource, $action = null)
             $action = $this->getDefaultAction($request);
         }
 
-        if ($this->can($resource, $action)) {
+        $result = $this->can($resource, $action);
+        if (!$result instanceof ResultInterface) {
+            $result = new Result($result);
+        }
+        if ($result->getStatus()) {
             return;
         }
 
@@ -76,7 +81,7 @@ public function authorize($resource, $action = null)
         } else {
             $name = gettype($resource);
         }
-        throw new ForbiddenException([$action, $name]);
+        throw new ForbiddenException($result, [$action, $name]);
     }
 
     /**
@@ -87,7 +92,7 @@ public function authorize($resource, $action = null)
      *
      * @param object $resource The resource to check authorization on.
      * @param string|null $action The action to check authorization for.
-     * @return bool
+     * @return bool|\Authorization\Policy\ResultInterface
      */
     public function can($resource, $action = null)
     {
@@ -97,15 +102,11 @@ public function can($resource, $action = null)
         }
 
         $identity = $this->getIdentity($request);
-        if (empty($identity) && $this->getService($this->request)->can(null, $action, $resource)) {
-            return true;
-        }
-
-        if (!empty($identity) && $identity->can($action, $resource)) {
-            return true;
+        if (empty($identity)) {
+            return $this->getService($this->request)->can(null, $action, $resource);
         }
 
-        return false;
+        return $identity->can($action, $resource);
     }
 
     /**

src/Exception/ForbiddenException.php

@@ -15,6 +15,8 @@
 
 namespace Authorization\Exception;
 
+use Authorization\Policy\ResultInterface;
+
 class ForbiddenException extends Exception
 {
     /**
@@ -26,4 +28,42 @@ class ForbiddenException extends Exception
      * {@inheritDoc}
      */
     protected $_messageTemplate = 'Identity is not authorized to perform `%s` on `%s`.';
+
+    /**
+     * Policy check result.
+     *
+     * @var \Authorization\Policy\ResultInterface|null
+     */
+    protected $result;
+
+    /**
+     * Constructor
+     *
+     * @param ResultInterface|null $result Policy check result.
+     * @param string|array $message Either the string of the error message, or an array of attributes
+     *   that are made available in the view, and sprintf()'d into Exception::$_messageTemplate
+     * @param int|null $code The code of the error, is also the HTTP status code for the error.
+     * @param \Exception|null $previous the previous exception.
+     */
+    public function __construct($result = null, $message = '', $code = null, $previous = null)
+    {
+        if ($result instanceof ResultInterface) {
+            $this->result = $result;
+
+            parent::__construct($message, $code, $previous);
+        } else {
+            //shift off first argument for BC
+            parent::__construct($result, $message, $code);
+        }
+    }
+
+    /**
+     * Returns policy check result if passed to the exception.
+     *
+     * @return \Authorization\Policy\ResultInterface|null
+     */
+    public function getResult()
+    {
+        return $this->result;
+    }
 }

src/IdentityInterface.php

@@ -30,7 +30,7 @@ interface IdentityInterface extends ArrayAccess
      *
      * @param string $action The action/operation being performed.
      * @param mixed $resource The resource being operated on.
-     * @return bool
+     * @return bool|\Authorization\Policy\ResultInterface
      */
     public function can($action, $resource);
 

src/Middleware/RequestAuthorizationMiddleware.php

@@ -16,6 +16,8 @@
 
 use Authorization\AuthorizationServiceInterface;
 use Authorization\Exception\ForbiddenException;
+use Authorization\Policy\Result;
+use Authorization\Policy\ResultInterface;
 use Cake\Core\InstanceConfigTrait;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
@@ -92,8 +94,12 @@ public function __invoke(ServerRequestInterface $request, ResponseInterface $res
         $service = $this->getServiceFromRequest($request);
         $identity = $request->getAttribute($this->getConfig('identityAttribute'));
 
-        if (!$service->can($identity, $this->getConfig('method'), $request)) {
-            throw new ForbiddenException();
+        $result = $service->can($identity, $this->getConfig('method'), $request);
+        if (!$result instanceof ResultInterface) {
+            $result = new Result($result);
+        }
+        if (!$result->getStatus()) {
+            throw new ForbiddenException($result);
         }
 
         return $next($request, $response);