<?php
/**
 * Router Contract
 *
 * @package Licenzo\Framework\Contracts\Router
 */

namespace Licenzo\Framework\Contracts\Router;

use Licenzo\Framework\Http\Request;

// Prevent direct access
if (!defined('ABSPATH')) {
    exit;
}

/**
 * Router interface for handling HTTP routes
 */
interface Router
{
    /**
     * Register a GET route
     *
     * @param string $uri
     * @param mixed $action
     * @return Route
     */
    public function get(string $uri, $action): Route;

    /**
     * Register a POST route
     *
     * @param string $uri
     * @param mixed $action
     * @return Route
     */
    public function post(string $uri, $action): Route;

    /**
     * Register a PUT route
     *
     * @param string $uri
     * @param mixed $action
     * @return Route
     */
    public function put(string $uri, $action): Route;

    /**
     * Register a DELETE route
     *
     * @param string $uri
     * @param mixed $action
     * @return Route
     */
    public function delete(string $uri, $action): Route;

    /**
     * Register a PATCH route
     *
     * @param string $uri
     * @param mixed $action
     * @return Route
     */
    public function patch(string $uri, $action): Route;

    /**
     * Create a route group with attributes
     *
     * @param array $attributes
     * @param \Closure $callback
     * @return void
     */
    public function group(array $attributes, \Closure $callback): void;

    /**
     * Create a middleware group
     *
     * @param string|array $middleware
     * @return RouteGroup
     */
    public function middleware(string|array $middleware): RouteGroup;

    /**
     * Create a policy group
     *
     * @param string $policy
     * @return RouteGroup
     */
    public function policy(string $policy): RouteGroup;

    /**
     * Match a request to a route
     *
     * @param Request $request
     * @return Route|null
     */
    public function match(Request $request): ?Route;

    /**
     * Register all routes with WordPress REST API
     *
     * @return void
     */
    public function dispatch(): void;

    /**
     * Get all registered routes
     *
     * @return array
     */
    public function getRoutes(): array;

    /**
     * Add a named route to the registry
     *
     * @param string $name
     * @param Route $route
     * @return void
     */
    public function addNamedRoute(string $name, Route $route): void;

    /**
     * Enable route caching
     *
     * @param bool $enabled
     * @return self
     */
    public function cache(bool $enabled = true): self;
}
