AccessPolicyInterface.php

<?php

namespace Drupal\Core\Session;


/**
 * Defines the access policy interface.
 *
 * Make sure that when calculating permissions, you attach the right cacheable
 * metadata. This includes cache contexts if your implementation causes the
 * calculated permissions to vary by something. Any cache contexts defined in
 * the getPersistentCacheContexts() methods must also be added to the
 * corresponding calculated permissions but Drupal\Core\Session\AccessPolicyBase
 * takes care of this for you.
 *
 * Do NOT use any cache context that relies on calculated permissions in any of
 * the calculations as you will end up in an infinite loop. E.g.: The cache
 * context "user.permissions" relies on your calculated Drupal permissions.
 */
interface AccessPolicyInterface {
    
    /**
     * Scope ID for general Drupal access.
     */
    const SCOPE_DRUPAL = 'drupal';
    
    /**
     * Checks whether this access policy applies to a given scope.
     *
     * @param string $scope
     *   The scope to check for.
     *
     * @return bool
     *   Whether this access policy applies to the given scope.
     */
    public function applies(string $scope) : bool;
    
    /**
     * Calculates the permissions for an account within a given scope.
     *
     * @param \Drupal\Core\Session\AccountInterface $account
     *   The user account for which to calculate the permissions.
     * @param string $scope
     *   The scope to calculate the permissions for.
     *
     * @return \Drupal\Core\Session\RefinableCalculatedPermissionsInterface
     *   An object representing the permissions within the given scope.
     */
    public function calculatePermissions(AccountInterface $account, string $scope) : RefinableCalculatedPermissionsInterface;
    
    /**
     * Alter the permissions after all policies have finished building them.
     *
     * This should only be used to revoke permissions. If you wish to add
     * permissions, you should write another access policy that uses the
     * calculatePermissions method instead.
     *
     * Keep in mind that there are many ways to alter access policy results.
     * Because each access policy itself is a service, the best way to get rid of
     * a specific access policy's permissions as a whole, is by removing said
     * access policy in your module's service provider.
     *
     * A good example use case of alterPermissions would be to revoke a banned
     * list of permissions outside of office hours. This would make it so no-one
     * can perform any destructive actions while the help desk is offline.
     *
     * @param \Drupal\Core\Session\AccountInterface $account
     *   The user account for which to alter the permissions.
     * @param string $scope
     *   The scope to alter the permissions for.
     * @param \Drupal\Core\Session\RefinableCalculatedPermissionsInterface $calculated_permissions
     *   The completely built calculated permissions.
     */
    public function alterPermissions(AccountInterface $account, string $scope, RefinableCalculatedPermissionsInterface $calculated_permissions) : void;
    
    /**
     * Gets the persistent cache contexts.
     *
     * These inform the system what your access policy's calculations always vary
     * by. If you have any further cache contexts that you want to conditionally
     * add, you can do so in calculatePermissions and alterPermissions.
     *
     * @return string[]
     *   The persistent cache contexts.
     */
    public function getPersistentCacheContexts() : array;

}