<?php

declare(strict_types=1);

namespace Instinctor\Core\Router;

/**
 * Router driver interface.
 *
 * On WordPress: wraps register_rest_route / add_rewrite_rule / template_redirect.
 * On Standalone: pure PHP front controller — index.php dispatches all requests here.
 */

if (!defined('ABSPATH')) exit;
interface DriverInterface
{
    /**
     * Register a REST API route.
     *
     * @param string          $method   HTTP method(s): 'GET', 'POST', 'PUT', 'DELETE', or 'GET,POST'
     * @param string          $path     Route path relative to API namespace, e.g. '/products' or '/products/(?P<id>\d+)'
     * @param callable        $handler  Request handler
     * @param array           $options  Optional: ['auth' => bool, 'schema' => callable, 'args' => array]
     */
    public function rest(string $method, string $path, callable $handler, array $options = []): void;

    /**
     * Register a named frontend route.
     *
     * On WP: maps to a page slug via template_redirect.
     * On standalone: regex route handled by front controller.
     *
     * @param string   $name     Route name, e.g. 'shop', 'checkout', 'account'
     * @param string   $pattern  URL pattern, e.g. '/shop', '/account/:section'
     * @param callable $handler  Handler receives extracted params array
     * @param array    $middleware  e.g. ['auth', 'admin']
     */
    public function add(string $name, string $pattern, callable $handler, array $middleware = []): void;

    /**
     * Dispatch the current request to a matching frontend route.
     * Called once per request: from template_redirect on WP, from index.php on standalone.
     */
    public function dispatch(): void;

    /**
     * Generate a URL for a named route with optional parameter substitution.
     *
     * @param string $name    Route name
     * @param array  $params  e.g. ['section' => 'orders'] for '/account/:section'
     */
    public function url(string $name, array $params = []): string;

    /**
     * Return the REST API base URL (with namespace).
     */
    public function restBase(): string;
}
