Outcome.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 Session - Outcome
 *
 * @package Italix\Session
 */

declare(strict_types=1);

namespace Italix\Session;

/**
 * What `Session::end()` decided, for the middleware to act on.
 *
 * The cookie is **returned as a string** rather than sent. `setcookie()` and
 * `header()` write to a place that does not exist under a resident worker, and
 * they are also untestable without a SAPI — which is how a session layer ends
 * up with no test for the one header that matters. Handing the value back means
 * the middleware puts it on a PSR-7 response and a suite can read it.
 */
final class Outcome
{
    private string $state_c;

    private ?string $id_c;

    private ?string $cookie_header_c;

    private bool $persisted_flag;

    public function __construct(
        string $state_c,
        ?string $id_c = null,
        ?string $cookie_header_c = null,
        bool $persisted_flag = false
    ) {
        $this->state_c         = $state_c;
        $this->id_c            = $id_c;
        $this->cookie_header_c = $cookie_header_c;
        $this->persisted_flag  = $persisted_flag;
    }

    public function state(): string
    {
        return $this->state_c;
    }

    public function token(): ?string
    {
        return $this->id_c;
    }

    /**
     * Whether a `Set-Cookie` has to go out.
     *
     * False for the common case — an unchanged session on an existing cookie —
     * because re-sending an identical cookie on every response is bytes for
     * nothing and defeats caching on the responses that could have been cached.
     */
    public function has_cookie(): bool
    {
        return $this->cookie_header_c !== null;
    }

    public function cookie_header(): string
    {
        return (string) $this->cookie_header_c;
    }

    /** Whether anything was actually written to the store. */
    public function is_persisted(): bool
    {
        return $this->persisted_flag;
    }
}