<?php

declare(strict_types=1);

namespace App\Framework\Http\Url;

/**
 * URL Use Case categories for automatic spec selection
 *
 * Helps determine whether RFC 3986 or WHATWG URL Standard
 * should be used based on the intended usage pattern.
 */
enum UrlUseCase
{
    /**
     * API Client requests (REST, GraphQL, SOAP)
     *
     * Recommended Spec: RFC 3986
     * - Strict parsing for API endpoints
     * - URL signature compatibility
     * - Predictable canonicalization
     */
    case API_CLIENT;

    /**
     * cURL requests and HTTP client operations
     *
     * Recommended Spec: RFC 3986
     * - Compatible with cURL expectations
     * - No automatic normalization
     * - Preserves exact URL structure
     */
    case CURL_REQUEST;

    /**
     * URL signature generation (OAuth, AWS, etc.)
     *
     * Recommended Spec: RFC 3986
     * - Deterministic URL formatting
     * - No automatic encoding changes
     * - Critical for signature validation
     */
    case SIGNATURE_GENERATION;

    /**
     * Canonical URL generation (SEO, duplicate detection)
     *
     * Recommended Spec: RFC 3986
     * - Consistent URL representation
     * - Reliable comparison
     * - SEO-friendly formatting
     */
    case CANONICAL_URL;

    /**
     * Browser redirect URLs
     *
     * Recommended Spec: WHATWG
     * - Browser-compatible behavior
     * - Automatic encoding
     * - Matches browser expectations
     */
    case BROWSER_REDIRECT;

    /**
     * Deep links (app-to-web, universal links)
     *
     * Recommended Spec: WHATWG
     * - Mobile browser compatibility
     * - Modern URL handling
     * - Cross-platform consistency
     */
    case DEEP_LINK;

    /**
     * HTML form action URLs
     *
     * Recommended Spec: WHATWG
     * - HTML5 specification compliance
     * - Browser form submission compatibility
     * - Automatic encoding of form data
     */
    case HTML_FORM_ACTION;

    /**
     * Client-side generated URLs (JavaScript compatibility)
     *
     * Recommended Spec: WHATWG
     * - Matches JavaScript URL API
     * - Compatible with fetch()
     * - Consistent with browser behavior
     */
    case CLIENT_SIDE_URL;

    /**
     * Get human-readable description of this use case
     */
    public function description(): string
    {
        return match ($this) {
            self::API_CLIENT => 'API client requests (REST, GraphQL, SOAP)',
            self::CURL_REQUEST => 'cURL requests and HTTP client operations',
            self::SIGNATURE_GENERATION => 'URL signature generation (OAuth, AWS)',
            self::CANONICAL_URL => 'Canonical URL generation (SEO)',
            self::BROWSER_REDIRECT => 'Browser redirect URLs',
            self::DEEP_LINK => 'Deep links and universal links',
            self::HTML_FORM_ACTION => 'HTML form action URLs',
            self::CLIENT_SIDE_URL => 'Client-side JavaScript URLs',
        };
    }

    /**
     * Get recommended URL spec for this use case
     */
    public function recommendedSpec(): UrlSpec
    {
        return UrlSpec::forUseCase($this);
    }
}
