<?php
/**
 * Event Interface
 *
 * Defines the contract for event objects in the event system.
 *
 * @package     WPUltimateSecurity\UltimateSecurity\Contracts
 * @since       2.0.0
 */

declare(strict_types=1);

namespace WPUltimateSecurity\UltimateSecurity\Contracts;

/**
 * Contract for event objects.
 *
 * Events carry information about something that has happened in the system.
 * They can be dispatched to subscribers and support propagation stopping.
 *
 * @since 2.0.0
 */
interface EventInterface
{
    /**
     * 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;

    /**
     * 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;

    /**
     * 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;

    /**
     * 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;
}
