breadcrumb-the-shire/lib/Support/Flash.php

<?php

namespace MintyPHP\Support;

use MintyPHP\Session;

// Session-based flash message store. Messages are written before a redirect and consumed on the next page.
class Flash
{
    private const SESSION_KEY = 'flash_messages';
    private const KEEP_KEY = 'flash_keep';

    private static function ensureSession()
    {
        if (session_status() !== PHP_SESSION_ACTIVE) {
            Session::start();
        }
        if (!isset($_SESSION[self::SESSION_KEY])) {
            $_SESSION[self::SESSION_KEY] = [];
        }
    }

    // If a key is given, any existing message with the same key+scope is replaced — prevents duplicate notices.
    public static function add(string $type, string $message, ?string $scope = null, ?string $key = null): string
    {
        self::ensureSession();
        if ($key !== null) {
            $_SESSION[self::SESSION_KEY] = array_values(array_filter(
                $_SESSION[self::SESSION_KEY],
                function ($existing) use ($key, $scope) {
                    $sameKey = ($existing['key'] ?? null) === $key;
                    $sameScope = ($existing['scope'] ?? null) === $scope;
                    return !($sameKey && $sameScope);
                }
            ));
        }
        $id = bin2hex(random_bytes(8));
        $_SESSION[self::SESSION_KEY][] = [
            'id' => $id,
            'type' => $type,
            'message' => $message,
            'scope' => $scope,
            'key' => $key,
        ];
        return $id;
    }

    public static function success(string $message, ?string $scope = null, ?string $key = null): string
    {
        return self::add('success', $message, $scope, $key);
    }

    public static function error(string $message, ?string $scope = null, ?string $key = null): string
    {
        return self::add('error', $message, $scope, $key);
    }

    public static function info(string $message, ?string $scope = null, ?string $key = null): string
    {
        return self::add('info', $message, $scope, $key);
    }

    public static function peek(?string $scope = null): array
    {
        self::ensureSession();
        $messages = $_SESSION[self::SESSION_KEY] ?? [];
        if ($scope === null) {
            return $messages;
        }

        return array_values(array_filter($messages, function ($message) use ($scope) {
            $messageScope = $message['scope'] ?? null;
            return $messageScope === null || $messageScope === $scope;
        }));
    }

    public static function has(): bool
    {
        self::ensureSession();
        return !empty($_SESSION[self::SESSION_KEY]);
    }

    public static function dismiss(string $id): void
    {
        self::ensureSession();
        $messages = $_SESSION[self::SESSION_KEY] ?? [];
        $messages = array_values(array_filter($messages, function ($message) use ($id) {
            return ($message['id'] ?? '') !== $id;
        }));

        if ($messages) {
            $_SESSION[self::SESSION_KEY] = $messages;
        } else {
            unset($_SESSION[self::SESSION_KEY]);
        }
    }

    /**
     * Remove all flash messages matching a given key (and optionally scope).
     */
    public static function dismissByKey(string $key, ?string $scope = null): void
    {
        self::ensureSession();
        $messages = $_SESSION[self::SESSION_KEY] ?? [];
        $messages = array_values(array_filter($messages, function ($message) use ($key, $scope) {
            if (($message['key'] ?? null) !== $key) {
                return true;
            }
            if ($scope !== null && ($message['scope'] ?? null) !== $scope) {
                return true;
            }
            return false;
        }));

        if ($messages) {
            $_SESSION[self::SESSION_KEY] = $messages;
        } else {
            unset($_SESSION[self::SESSION_KEY]);
        }
    }

    // Prevents messages from being cleared on the next render — useful when a redirect chain crosses multiple pages.
    public static function keep(int $times = 1)
    {
        self::ensureSession();
        $times = max(1, $times);
        $current = (int) ($_SESSION[self::KEEP_KEY] ?? 0);
        $_SESSION[self::KEEP_KEY] = max($current, $times);
    }
}