TestSession.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 Testing - TestSession
 *
 * @package Italix\Testing
 */

declare(strict_types=1);

namespace Italix\Testing;

/**
 * Starts a real PHP session when that is still possible, and shrugs when it is
 * not.
 *
 * Measured, not assumed, on PHP 8.1 CLI:
 *
 *   - `session_start()` fails once anything has been printed, because CLI sets
 *     `headers_sent()` on the first byte of output. Options do not help; an
 *     active output buffer does, but only if it was opened before that byte.
 *   - `$_SESSION` is an ordinary superglobal. Writing to it without a session
 *     works, and application code that reads `$_SESSION['admin_id']`
 *     cannot tell the difference.
 *
 * So a real session is a *nicety*, not a requirement: it is worth having only
 * because application middleware calls `session_start()` itself, and that call
 * emits a warning into the test output when it cannot succeed. Starting the
 * session first — which `Runner::suite()` does before it prints its header —
 * makes the middleware's call a no-op and the output clean.
 *
 * When it is too late, this class does nothing and the suite still runs
 * correctly. Refusing to run would be trading a working test for a tidy one.
 */
final class TestSession
{
    private static bool $attempted = false;

    private function __construct()
    {
    }

    /**
     * Ensure a session exists, if one still can.
     *
     * @return bool true when a real PHP session is active
     */
    public static function ensure_started(): bool
    {
        if (session_status() === PHP_SESSION_ACTIVE) {
            return true;
        }

        if (self::$attempted || headers_sent()) {
            // Already tried, or too late to try. $_SESSION still works.
            self::$attempted = true;

            return false;
        }

        self::$attempted = true;

        if (PHP_SAPI === 'cli') {
            // The default save path is often unwritable for the CLI user, and
            // a cookie has nowhere to go.
            @session_save_path(sys_get_temp_dir());
            @ini_set('session.use_cookies', '0');
            @ini_set('session.cache_limiter', '');
        }

        @session_start();

        return session_status() === PHP_SESSION_ACTIVE;
    }

    /**
     * Whether a real PHP session backs $_SESSION right now.
     */
    public static function is_active(): bool
    {
        return session_status() === PHP_SESSION_ACTIVE;
    }
}