<?php

declare(strict_types=1);

namespace App\Framework\Reflection\Contracts;

use App\Framework\Core\ValueObjects\ClassName;
use App\Framework\Reflection\Collections\AttributeCollection;

/**
 * Interface for attribute-related reflection operations
 */
interface AttributeReflector
{
    /**
     * Get attributes for a class
     *
     * @param ClassName $className The class name to get attributes for
     * @param string|null $attributeClass Optional attribute class to filter by
     * @return AttributeCollection Collection of attributes
     */
    public function getAttributes(ClassName $className, ?string $attributeClass = null): AttributeCollection;

    /**
     * Get attributes for a method
     *
     * @param ClassName $className The class name containing the method
     * @param string $methodName The method name to get attributes for
     * @param string|null $attributeClass Optional attribute class to filter by
     * @return AttributeCollection Collection of attributes
     */
    public function getMethodAttributes(ClassName $className, string $methodName, ?string $attributeClass = null): AttributeCollection;

    /**
     * Check if a class has a specific attribute
     *
     * @param ClassName $className The class name to check
     * @param string $attributeClass The attribute class to check for
     * @return bool True if the class has the attribute, false otherwise
     */
    public function hasAttribute(ClassName $className, string $attributeClass): bool;

    /**
     * Check if a method has a specific attribute
     *
     * @param ClassName $className The class name containing the method
     * @param string $methodName The method name to check
     * @param string $attributeClass The attribute class to check for
     * @return bool True if the method has the attribute, false otherwise
     */
    public function hasMethodAttribute(ClassName $className, string $methodName, string $attributeClass): bool;

    /**
     * Get attribute instances for a class (PHP 8.0+)
     *
     * @param ClassName $className The class name to get attribute instances for
     * @param string|null $attributeClass Optional attribute class to filter by
     * @return array<object> Array of instantiated attribute objects
     */
    public function getAttributeInstances(ClassName $className, ?string $attributeClass = null): array;

    /**
     * Get attribute instances for a method (PHP 8.0+)
     *
     * @param ClassName $className The class name containing the method
     * @param string $methodName The method name to get attribute instances for
     * @param string|null $attributeClass Optional attribute class to filter by
     * @return array<object> Array of instantiated attribute objects
     */
    public function getMethodAttributeInstances(ClassName $className, string $methodName, ?string $attributeClass = null): array;
}
