<?php

declare(strict_types=1);

namespace App\Framework\Http\Url;

/**
 * URL Specification identifier
 *
 * Distinguishes between RFC 3986 and WHATWG URL Standard
 * for different parsing and handling semantics.
 */
enum UrlSpec: string
{
    /**
     * RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax
     *
     * Use for:
     * - Server-side URL canonicalization
     * - API clients (REST, GraphQL, SOAP)
     * - URL signatures and validation
     * - cURL compatibility
     * - File system paths
     *
     * Characteristics:
     * - Strict parsing rules
     * - No automatic encoding
     * - No URL normalization
     * - Preserves original structure
     *
     * Example:
     * ```php
     * $uri = Rfc3986Url::parse('https://api.example.com/users?id=123');
     * ```
     */
    case RFC3986 = 'rfc3986';

    /**
     * WHATWG URL Standard (Living Standard)
     *
     * Use for:
     * - Browser-like URL handling
     * - Deep links and redirects
     * - Client-side generated URLs
     * - HTML form actions
     * - JavaScript fetch() API compatibility
     *
     * Characteristics:
     * - Living standard (matches modern browsers)
     * - Automatic percent-encoding
     * - URL normalization
     * - Special scheme handling (http, https, file, etc.)
     *
     * Example:
     * ```php
     * $url = WhatwgUrl::parse('https://example.com/redirect');
     * ```
     */
    case WHATWG = 'whatwg';

    /**
     * Get recommended spec for specific use case
     *
     * Automatically selects the appropriate URL specification
     * based on the intended usage pattern.
     */
    public static function forUseCase(UrlUseCase $useCase): self
    {
        return match ($useCase) {
            UrlUseCase::API_CLIENT,
            UrlUseCase::CURL_REQUEST,
            UrlUseCase::SIGNATURE_GENERATION,
            UrlUseCase::CANONICAL_URL => self::RFC3986,

            UrlUseCase::BROWSER_REDIRECT,
            UrlUseCase::DEEP_LINK,
            UrlUseCase::HTML_FORM_ACTION,
            UrlUseCase::CLIENT_SIDE_URL => self::WHATWG,
        };
    }

    /**
     * Check if this spec is RFC 3986
     */
    public function isRfc3986(): bool
    {
        return $this === self::RFC3986;
    }

    /**
     * Check if this spec is WHATWG
     */
    public function isWhatwg(): bool
    {
        return $this === self::WHATWG;
    }
}