rspade_system/app/RSpade/Lib/Flash/Flash_Alert.php

<?php
/**
 * CODING CONVENTION:
 * This file follows the coding convention where variable_names and function_names
 * use snake_case (underscore_wherever_possible).
 */

namespace App\RSpade\Lib\Flash;

use App\RSpade\Core\Session\Session;
use App\RSpade\Lib\Flash\Flash_Alert_Model;

/**
 * Flash_Alert - Server-side flash message system
 *
 * Provides a simple API for creating flash messages that will be delivered
 * to the client via page rendering or Ajax responses. Messages are stored
 * in the database and expire after 1 minute if not rendered.
 *
 * Usage:
 *   Flash_Alert::success('Account created successfully!');
 *   Flash_Alert::error('Invalid email address');
 *   Flash_Alert::info('Your session will expire in 5 minutes');
 *   Flash_Alert::warning('This action cannot be undone');
 *
 * Messages are automatically:
 * - Included in window.rsxapp.flash_alerts on page render
 * - Included in Ajax response.flash_alerts for Ajax calls
 * - Displayed via Flash_Alert JavaScript class on client
 * - Deleted after being retrieved for rendering
 * - Expired after 1 minute if not rendered
 */
class Flash_Alert
{
    /**
     * Create a success flash message
     *
     * @param string $message The message to display
     * @return void
     */
    public static function success(string $message): void
    {
        static::_create_message($message, Flash_Alert_Model::TYPE_SUCCESS);
    }

    /**
     * Create an error flash message
     *
     * @param string $message The message to display
     * @return void
     */
    public static function error(string $message): void
    {
        static::_create_message($message, Flash_Alert_Model::TYPE_ERROR);
    }

    /**
     * Create an info flash message
     *
     * @param string $message The message to display
     * @return void
     */
    public static function info(string $message): void
    {
        static::_create_message($message, Flash_Alert_Model::TYPE_INFO);
    }

    /**
     * Create a warning flash message
     *
     * @param string $message The message to display
     * @return void
     */
    public static function warning(string $message): void
    {
        static::_create_message($message, Flash_Alert_Model::TYPE_WARNING);
    }

    /**
     * Get all pending flash messages for current session
     *
     * Returns array of messages and deletes them from database.
     * Also deletes any messages older than 1 minute (expired).
     *
     * @return array Array of ['type' => 'success'|'error'|'info'|'warning', 'message' => '...']
     */
    public static function get_pending_messages(): array
    {
        $session_id = Session::get_session_id();
        if ($session_id === null) {
            return [];
        }

        // Delete expired messages (older than 1 minute)
        Flash_Alert_Model::where('session_id', $session_id)
            ->where('created_at', '<', now()->subMinute())
            ->delete();

        // Get all pending flash alerts for this session
        $alerts = Flash_Alert_Model::where('session_id', $session_id)
            ->orderBy('created_at', 'asc')
            ->get();

        if ($alerts->isEmpty()) {
            return [];
        }

        // Delete the alerts now that we're retrieving them
        Flash_Alert_Model::where('session_id', $session_id)
            ->delete();

        // Convert to client format
        $messages = [];
        foreach ($alerts as $alert) {
            $messages[] = [
                'type' => $alert->get_type_string(),
                'message' => $alert->message,
            ];
        }

        return $messages;
    }

    /**
     * Create a flash message in the database
     *
     * @param string $message The message text
     * @param int $type_id The type ID (use Flash_Alert_Model constants)
     * @return void
     */
    protected static function _create_message(string $message, int $type_id): void
    {
        $session_id = Session::get_session_id();
        if ($session_id === null) {
            return;
        }

        $flash_alert = new Flash_Alert_Model();
        $flash_alert->session_id = $session_id;
        $flash_alert->type_id = $type_id;
        $flash_alert->message = $message;
        $flash_alert->created_at = now();
        $flash_alert->save();
    }
}