<?php
/**
 * Abstract Event Base Class
 *
 * Provides a base implementation of the EventInterface for creating
 * concrete event classes in the event system.
 *
 * @package     WPUltimateSecurity\UltimateSecurity\Events
 * @since       2.0.0
 */

declare(strict_types=1);

namespace WPUltimateSecurity\UltimateSecurity\Events;

use WPUltimateSecurity\UltimateSecurity\Contracts\EventInterface;

/**
 * Abstract base class for event objects.
 *
 * Provides common functionality for all events including name storage,
 * payload management, and propagation control. Extend this class to
 * create specific event types.
 *
 * @since 2.0.0
 */
abstract class AbstractEvent implements EventInterface
{
    /**
     * The event name.
     *
     * Unique identifier for this event type, typically in dot notation
     * (e.g., 'user.login', 'security.lockout').
     *
     * @since 2.0.0
     *
     * @var string
     */
    protected string $name;

    /**
     * The event payload data.
     *
     * Contains the data associated with this event. Structure varies
     * by event type and should be documented by each concrete class.
     *
     * @since 2.0.0
     *
     * @var array<string, mixed>
     */
    protected array $payload;

    /**
     * Whether event propagation has been stopped.
     *
     * When true, the event dispatcher should stop notifying
     * subsequent subscribers.
     *
     * @since 2.0.0
     *
     * @var bool
     */
    protected bool $propagationStopped = false;

    /**
     * Create a new event instance.
     *
     * @since 2.0.0
     *
     * @param string              $name    The event name identifier.
     * @param array<string, mixed> $payload Optional payload data for the event.
     */
    public function __construct(string $name, array $payload = [])
    {
        $this->name    = $name;
        $this->payload = $payload;
    }

    /**
     * Get the event name.
     *
     * Returns a unique identifier for this event type, typically in
     * dot notation (e.g., 'user.login', 'security.lockout').
     *
     * @since 2.0.0
     *
     * @return string The event name.
     */
    public function getName(): string
    {
        return $this->name;
    }

    /**
     * Get the event payload.
     *
     * Returns the data associated with this event. The payload structure
     * varies by event type but should be documented by each event class.
     *
     * @since 2.0.0
     *
     * @return array<string, mixed> The event payload data.
     */
    public function getPayload(): array
    {
        return $this->payload;
    }

    /**
     * Stop event propagation.
     *
     * Once called, no further subscribers will be notified of this event.
     * Useful when a subscriber has fully handled the event.
     *
     * @since 2.0.0
     *
     * @return void
     */
    public function stopPropagation(): void
    {
        $this->propagationStopped = true;
    }

    /**
     * Check if propagation has been stopped.
     *
     * The event dispatcher should check this after each subscriber
     * to determine whether to continue notification.
     *
     * @since 2.0.0
     *
     * @return bool True if propagation has been stopped.
     */
    public function isPropagationStopped(): bool
    {
        return $this->propagationStopped;
    }
}
