Name	Size	Mode	Actions
2-0-migration-guide.rst	790	0644	editdlrm
checking-authorization.rst	2138	0644	editdlrm
component.rst	4503	0644	editdlrm
conf.py	261	0644	editdlrm
contents.rst	255	0644	editdlrm
index.rst	3856	0644	editdlrm
middleware.rst	10912	0644	editdlrm
policies.rst	4243	0644	editdlrm
policy-resolvers.rst	5334	0644	editdlrm
request-authorization-middleware.rst	2939	0644	editdlrm

Policies ######## Policies are classes that resolve permissions for a given object. You can create policies for any class in your application that you wish to apply permissions checks to. 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 :doc:`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:: 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: 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. Policy Scopes ------------- In addition to policies being able to define pass/fail authorization checks, they can also define 'scopes'. Scope methods allow you to modify another object applying authorization conditions. A perfect use case for this is restricting a list view to the current user:: namespace App\Policy; class ArticlesTablePolicy { public function scopeIndex($user, $query) { return $query->where(['Articles.user_id' => $user->getIdentifier()]); } } Policy Pre-conditions --------------------- In some policies you may wish to apply common checks across all operations in a policy. This is useful when you need to deny all actions to the provided resource. To use pre-conditions you need to implement the ``BeforePolicyInterface`` in your policy:: 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 } } Before hooks are expected to return one of three values: - ``true`` The user is allowed to proceed with the action. - ``false`` The user is not allowed to proceed with the action. - ``null`` The before hook did not make a decision, and the authorization method will be invoked.