<?php
/**
 * WP AI Client: WP_AI_Client_Event_Dispatcher class
 *
 * @package WordPress
 * @subpackage AI
 * @since 7.0.0
 */

use WordPress\AiClientDependencies\Psr\EventDispatcher\EventDispatcherInterface;

/**
 * WordPress-specific PSR-14 event dispatcher for the AI Client.
 *
 * Bridges PSR-14 events to WordPress action hooks, enabling plugins to hook
 * into AI client lifecycle events.
 *
 * @since 7.0.0
 * @internal Intended only to wire up the PHP AI Client SDK to WordPress's hook system.
 * @access private
 */
class WP_AI_Client_Event_Dispatcher implements EventDispatcherInterface {

    /**
     * Dispatches an event to WordPress action hooks.
     *
     * Converts the event class name to a WordPress action hook name and fires it.
     * For example, BeforeGenerateResultEvent becomes wp_ai_client_before_generate_result.
     *
     * @since 7.0.0
     *
     * @param object $event The event object to dispatch.
     * @return object The same event object, potentially modified by listeners.
     */
    public function dispatch( object $event ): object {
        $event_name = $this->get_hook_name_portion_for_event( $event );

        /**
         * Fires when an AI client event is dispatched.
         *
         * The dynamic portion of the hook name, `$event_name`, refers to the
         * snake_case version of the event class name, without the `_event` suffix.
         *
         * For example, an event class named `BeforeGenerateResultEvent` will fire the
         * `wp_ai_client_before_generate_result` action hook.
         *
         * In practice, the available action hook names are:
         *
         * - wp_ai_client_before_generate_result
         * - wp_ai_client_after_generate_result
         *
         * @since 7.0.0
         *
         * @param object $event The event object.
         */
        do_action( "wp_ai_client_{$event_name}", $event );

        return $event;
    }

    /**
     * Converts an event object class name to a WordPress action hook name portion.
     *
     * @since 7.0.0
     *
     * @param object $event The event object.
     * @return string The hook name portion derived from the event class name.
     */
    private function get_hook_name_portion_for_event( object $event ): string {
        $class_name = get_class( $event );
        $pos        = strrpos( $class_name, '\\' );
        $short_name = false !== $pos ? substr( $class_name, $pos + 1 ) : $class_name;

        // Convert PascalCase to snake_case.
        $snake_case = strtolower( (string) preg_replace( '/([a-z])([A-Z])/', '$1_$2', $short_name ) );

        // Strip '_event' suffix if present.
        if ( str_ends_with( $snake_case, '_event' ) ) {
            $snake_case = (string) substr( $snake_case, 0, -6 );
        }

        return $snake_case;
    }
}