<?php

declare(strict_types=1);

namespace App\Framework\TypeCaster;

/**
 * Universal type casting interface for converting between strings and Value Objects
 * Used across the framework for database, routing, API, and form handling
 */
interface TypeCasterInterface
{
    /**
     * Convert from string representation to Value Object
     *
     * @param string $value The string value to convert
     * @return mixed The Value Object instance
     * @throws \InvalidArgumentException If the value cannot be converted
     */
    public function fromString(string $value): mixed;

    /**
     * Convert from Value Object to string representation
     *
     * @param mixed $value The Value Object to convert
     * @return string The string representation
     * @throws \InvalidArgumentException If the value is not of expected type
     */
    public function toString(mixed $value): string;

    /**
     * Check if this caster supports the given type
     *
     * @param string $type The fully qualified class name to check
     * @return bool True if this caster can handle the type
     */
    public function supports(string $type): bool;

    /**
     * Get regex pattern for validation (routes, forms, etc.)
     *
     * @return string Regular expression pattern without delimiters
     */
    public function getPattern(): string;
}
