Gate.php

<?php
/*
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */
/**
 * Italix Auth - Gate
 *
 * @package Italix\Auth
 */

declare(strict_types=1);

namespace Italix\Auth;

/**
 * Asks the policies and decides.
 *
 *     if (!$gate->allows('post.edit', $who, $post)) {
 *         return $this->redirect_to($this->index_url($lang));
 *     }
 *
 * ## The two rules that make the result predictable
 *
 * **Deny wins.** A policy returning false ends the question; no later policy
 * can grant what an earlier one refused. Without that, adding a permissive
 * policy silently widens every existing restriction.
 *
 * **Silence is denial.** If every policy abstains, the answer is *no*. An
 * unrecognised action must not be permitted merely because nobody thought to
 * forbid it — that is how a typo in an action name becomes an open door.
 *
 * `explain()` returns which policy decided, because "why can this user not edit
 * this record?" is a question that gets asked at three in the afternoon by
 * someone who cannot reproduce it.
 */
final class Gate
{
    /** @var Policy[] */
    private array $policies;

    /**
     * @param Policy[] $policies consulted in order; the first non-null wins
     */
    public function __construct(array $policies = [])
    {
        foreach ($policies as $policy) {
            if (!$policy instanceof Policy) {
                throw new AuthException(
                    'A gate takes ' . Policy::class . ' instances; got '
                    . (is_object($policy) ? get_class($policy) : gettype($policy)) . '.'
                );
            }
        }

        $this->policies = array_values($policies);
    }

    public function with(Policy $policy): self
    {
        return new self(array_merge($this->policies, [$policy]));
    }

    /**
     * @param mixed|null $subject
     */
    public function allows(string $action_c, ?Identity $who, $subject = null): bool
    {
        if ($action_c === '') {
            throw new AuthException('An empty action can never be decided; name it.');
        }

        // No identity is not "abstain": it is nobody, and nobody may act.
        if ($who === null) {
            return false;
        }

        foreach ($this->policies as $policy) {
            $verdict = $policy->decide($action_c, $who, $subject);

            if ($verdict !== null) {
                return $verdict;
            }
        }

        return false;
    }

    /**
     * @param mixed|null $subject
     */
    public function denies(string $action_c, ?Identity $who, $subject = null): bool
    {
        return !$this->allows($action_c, $who, $subject);
    }

    /**
     * Who decided, and what. For the support ticket.
     *
     * @param  mixed|null $subject
     * @return array{allowed: bool, decided_by: string, reason_c: string}
     */
    public function explain(string $action_c, ?Identity $who, $subject = null): array
    {
        if ($who === null) {
            return ['allowed' => false, 'decided_by' => '', 'reason_c' => 'no_identity'];
        }

        foreach ($this->policies as $policy) {
            $verdict = $policy->decide($action_c, $who, $subject);

            if ($verdict !== null) {
                return [
                    'allowed'    => $verdict,
                    'decided_by' => get_class($policy),
                    'reason_c'   => $verdict ? 'allowed' : 'denied',
                ];
            }
        }

        return ['allowed' => false, 'decided_by' => '', 'reason_c' => 'no_policy_answered'];
    }

    /**
     * @return string[] registered policy class names, in consultation order
     */
    public function policies(): array
    {
        return array_map('get_class', $this->policies);
    }
}