CheckResult.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 Rules - CheckResult
 *
 * @package Italix\Rules
 * @license MPL-2.0
 */

declare(strict_types=1);

namespace Italix\Rules;

/**
 * The verdict on a single value.
 *
 * Carries:
 *
 *   - whether the value passed;
 *   - **whether it was actually verified**, which is not the same thing;
 *   - a machine-readable reason when it did not pass ('checksum', 'length', …),
 *     so the application can translate it — the engine never returns prose;
 *   - the canonical form of the value ('it60 x054 …' -> 'IT60X054…'), so the
 *     caller can store what it just validated rather than what was typed.
 *
 * ## Why there are three outcomes and not two
 *
 * A check that has no algorithm for a value's country used to answer `pass`.
 * That is a lie with a straight face: a made-up German VAT number came back
 * valid because the check only knew the Italian one and let everything else
 * through a shape test. Measured, before this was fixed.
 *
 * So there is a third answer: **unknown** — "nothing here contradicts it, and
 * nothing here confirms it".
 *
 * `is_valid()` stays **true** for unknown, deliberately. Making it false would
 * turn every foreign identifier into a blocking error overnight, in every
 * application already using this library. Instead the new question gets a new
 * predicate — `is_verified()` — so existing code keeps its behaviour and code
 * that cares can ask.
 *
 * Example:
 *
 *     $result = $checker->check('iban', $value);
 *     if (!$result->is_valid()) {
 *         $errors['fund_iban'] = $t->get('rules.iban.' . $result->error_code());
 *     } else {
 *         $data['fund_iban'] = $result->normalized();
 *
 *         if (!$result->is_verified()) {
 *             $notes[] = 'not checkable here — verify by hand';
 *         }
 *     }
 */
class CheckResult
{
    /** @var bool */
    private $valid;

    /** @var bool Whether an actual algorithm ran, as opposed to nothing objecting */
    private $verified;

    /** @var string Canonical form of the value; equals the input when unchanged */
    private $normalized;

    /** @var string|null Machine-readable failure reason, null when valid */
    private $error_c;

    /** @var array Extra context for the message, e.g. ['expected' => 27] */
    private $params;

    /**
     * @param bool        $valid
     * @param string      $normalized
     * @param string|null $error_c
     * @param array       $params
     */
    private function __construct(
        bool $valid,
        string $normalized,
        ?string $error_c = null,
        array $params = [],
        bool $verified = true
    ) {
        $this->valid      = $valid;
        $this->normalized = $normalized;
        $this->error_c    = $error_c;
        $this->params     = $params;
        $this->verified   = $verified;
    }

    /**
     * @param string $normalized The canonical form of the accepted value
     * @return self
     */
    public static function pass(string $normalized): self
    {
        return new self(true, $normalized);
    }

    /**
     * @param string $error_c    Machine-readable reason, e.g. 'checksum'
     * @param string $normalized Best-effort canonical form (for echoing back)
     * @param array  $params     Extra context for the message
     * @return self
     */
    public static function fail(string $error_c, string $normalized = '', array $params = []): self
    {
        return new self(false, $normalized, $error_c, $params);
    }

    /**
     * Nothing contradicted the value, and nothing confirmed it either.
     *
     * For the case a check genuinely cannot answer — most often a country it
     * carries no algorithm for. The alternative, answering `pass`, is a
     * confident wrong answer; answering `fail` would reject data that is very
     * probably fine.
     *
     * `$params` should say why, e.g. `['country_c' => 'DE']`, so a report can
     * name the reason without the library inventing a sentence.
     *
     * @param string $normalized Best-effort canonical form
     * @param array  $params     Context — conventionally the country
     * @return self
     */
    public static function unknown(string $normalized, array $params = []): self
    {
        return new self(true, $normalized, null, $params, false);
    }

    /**
     * True when nothing objected — including when nothing was actually checked.
     *
     * Pair with {@see is_verified()} before treating a value as confirmed.
     *
     * @return bool
     */
    public function is_valid(): bool
    {
        return $this->valid;
    }

    /**
     * True when an algorithm actually ran and reached a conclusion.
     *
     * False only for {@see unknown()} — a passing check and a failing one have
     * both concluded something.
     *
     * @return bool
     */
    public function is_verified(): bool
    {
        return $this->verified;
    }

    /**
     * True when the value passed *and* the passing was earned.
     *
     * The predicate most callers want when the answer decides something
     * irreversible.
     *
     * @return bool
     */
    public function is_confirmed(): bool
    {
        return $this->valid && $this->verified;
    }

    /**
     * Machine-readable failure reason; null when the value passed.
     *
     * @return string|null
     */
    public function error_code(): ?string
    {
        return $this->error_c;
    }

    /**
     * Canonical form of the value — safe to persist when is_valid() is true.
     *
     * @return string
     */
    public function normalized(): string
    {
        return $this->normalized;
    }

    /**
     * @return array
     */
    /**
     * The same verdict, carrying more context.
     *
     * A dispatcher answers with the verdict of the check it chose, but the
     * caller also needs to know *what was chosen* — that a national id was
     * verified as a register number and not a tax one. Immutable, like the rest
     * of this object: a result that could be edited is a result nobody can rely
     * on having read.
     *
     * @param array<string, mixed> $params merged over the existing ones
     */
    public function with_params(array $params): self
    {
        $copy = clone $this;
        $copy->params = $params + $this->params;

        return $copy;
    }

    public function get_params(): array
    {
        return $this->params;
    }

    /**
     * @return array
     */
    public function to_array(): array
    {
        return [
            'valid'      => $this->valid,
            'verified'   => $this->verified,
            'error_c'    => $this->error_c,
            'normalized' => $this->normalized,
            'params'     => $this->params,
        ];
    }
}