Policies¶

Creating Policies¶

You can create policies in your src/Policy directory. Policy classes don’t have a common base class or interface they are expected to implement. Application classes are then ‘resolved’ to a matching policy class. See the Policy Resolvers section for how policies can be resolved.

Generally you’ll want to put your policies in src/Policy and use the Policy class suffix. For now we’ll create a policy class for the Article entity in our application. In src/Policy/ArticlePolicy.php put the following content:

<?php
namespace App\Policy;

use App\Model\Entity\Article;
use Authorization\IdentityInterface;

class ArticlePolicy
{
}

In addition to entities, table objects and queries can have policies resolved. Query objects will have their repository() method called, and a policy class will be generated based on the table name. A table class of App\Model\Table\ArticlesTable will map to App\Policy\ArticlesTablePolicy.

Writing Policy Methods¶

The policy class we just created doesn’t do much right now. Lets define a method that allows us to check if a user can update an article:

public function canUpdate(IdentityInterface $user, Article $article)
{
    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 anonymous users you can use the IdentityInterface typehint.

Policy Result Objects¶

In addition to booleans, policy methods can return a Result object. Result objects allow more context to be provided on why the policy passed/failed:

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.

namespace App\Policy;

class ArticlesTablePolicy
{
    public function scopeIndex($user, $query)
    {
        return $query->where(['Articles.user_id' => $user->getIdentifier()]);
    }
}

namespace App\Policy;

use Authorization\Policy\BeforePolicyInterface;

class ArticlesPolicy implements BeforePolicyInterface
{
    public function before($user, $resource, $action)
    {
        if ($user->getOriginalData()->is_admin) {
            return true;
        }
        // fall through
    }
}