<?php

declare(strict_types=1);

namespace App\Framework\Discovery\Interfaces;

use App\Framework\Core\ValueObjects\ClassName;
use App\Framework\Filesystem\ValueObjects\FilePath;
use App\Framework\Reflection\WrappedReflectionClass;

/**
 * Interface for visitors that discover items from PHP classes
 *
 * Used for discovering attributes, routes, or other class-based metadata.
 * Provides direct access to cached reflection objects for optimal performance.
 */
interface ClassDiscoveryVisitor
{
    /**
     * Visit a PHP class during discovery
     *
     * This method is called for each discovered class file with pre-built reflection data.
     * Visitors should extract relevant information from the class metadata, attributes,
     * methods, or properties using the provided reflection object.
     *
     * @param ClassName $className The fully qualified class name
     * @param FilePath $filePath The path to the file containing the class
     * @param WrappedReflectionClass $reflection Cached reflection object for the class
     */
    public function visitClass(ClassName $className, FilePath $filePath, WrappedReflectionClass $reflection): void;
}
