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

declare(strict_types=1);

namespace Italix\Testing;

use PDO;
use Throwable;

/**
 * The test database, from the environment and from nowhere else.
 *
 * A library suite that reaches into an application's configuration directory
 * for credentials cannot be run by anyone else — it stops being a test of the
 * library and becomes a test of one deployment. So the connection comes from
 * three environment variables and the suite skips cleanly when they are absent:
 *
 *     ITALIX_TEST_DSN=mysql:host=127.0.0.1;dbname=italix_test;charset=utf8mb4
 *     ITALIX_TEST_USER=…
 *     ITALIX_TEST_PASSWORD=…
 *
 * How they get set is the *consumer's* problem. In this repository `ix test`
 * exports them from the site's own `.env` before running the suites, which
 * keeps the coverage without putting the coupling in the library.
 *
 * **Skipped is not passed.** `skip_notice()` prints why, and the caller reports
 * nothing as green — a suite that silently pretends to have run is worse than
 * one that admits it did not.
 */
final class Database
{
    public const DSN_VAR      = 'ITALIX_TEST_DSN';
    public const USER_VAR     = 'ITALIX_TEST_USER';
    public const PASSWORD_VAR = 'ITALIX_TEST_PASSWORD';

    private function __construct()
    {
    }

    /**
     * A connection, or null when the environment does not describe one.
     */
    public static function connect(): ?PDO
    {
        $dsn = self::env(self::DSN_VAR);

        if ($dsn === null) {
            return null;
        }

        try {
            return new PDO(
                $dsn,
                self::env(self::USER_VAR) ?? '',
                self::env(self::PASSWORD_VAR) ?? '',
                [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]
            );
        } catch (Throwable $e) {
            self::$last_error_c = $e->getMessage();

            return null;
        }
    }

    public static function is_available(): bool
    {
        return self::env(self::DSN_VAR) !== null;
    }

    /**
     * The line a suite prints instead of pretending it ran.
     */
    public static function skip_notice(string $what): string
    {
        $why = self::env(self::DSN_VAR) === null
            ? self::DSN_VAR . ' is not set'
            : 'could not connect: ' . (self::$last_error_c ?? 'unknown error');

        return "  SKIPPED — {$what} needs a database ({$why}).\n"
             . "  Nothing here is reported as passing.\n";
    }

    /**
     * Which driver the DSN names — for the handful of assertions that differ.
     */
    public static function driver_code(): string
    {
        $dsn = self::env(self::DSN_VAR);
        $pos = $dsn === null ? false : strpos($dsn, ':');

        return $pos === false ? '' : substr((string) $dsn, 0, $pos);
    }

    private static ?string $last_error_c = null;

    private static function env(string $name): ?string
    {
        $value = $_ENV[$name] ?? getenv($name);

        return is_string($value) && trim($value) !== '' ? $value : null;
    }
}