adachsoft/static-class-finder

Static Class Finder

A robust PHP library that resolves the file path of a class based on its Fully Qualified Class Name (FQCN) using only static Composer maps. It also provides an advanced facade (ClassFinder) for searching classes by prefix, partial name, regex, or similarity.

Features

• Static-only resolution: Uses Composer's generated metadata files (autoload_classmap.php, autoload_psr4.php, autoload_namespaces.php) and never scans the filesystem recursively.
• No reflection: Does not load or execute the target class. Safe for files with syntax errors.
• Aggregated sources: Combines multiple static sources (classmap + PSR-4/PSR-0) with deduplicated class names.
• Lazy loading: Loads Composer maps only when needed and caches them in memory.
• Lightweight dependencies: Requires PHP 8.3+ and one runtime dependency (adachsoft/collection).
• Advanced searching: Find classes by namespace prefix, partial name, regular expression, or Levenshtein similarity through the ClassFinder facade.
• Detailed results: Returns lightweight ClassLocationDto objects with FQCN and an optional relative path (null when the file does not exist anymore).

Installation

composer require adachsoft/static-class-finder

Usage

Basic: Locating a single class

use AdachSoft\StaticClassFinder\Locator;

// Initialize with the root path of the target project (where composer.json lives)
$projectRoot = '/var/www/target-project';
$locator = new Locator($projectRoot);

// Locate a class file
$filePath = $locator->locate('Monolog\Logger');

if ($filePath) {
    echo "File found: " . $filePath;
    // Output: vendor/monolog/monolog/src/Monolog/Logger.php (relative to project root)
} else {
    echo "Class not found.";
}

Advanced: Searching classes

use AdachSoft\StaticClassFinder\ClassFinder;
use AdachSoft\StaticClassFinder\Enum\CaseSensitivityEnum;
use AdachSoft\StaticClassFinder\Enum\MatchTargetEnum;

$classFinder = ClassFinder::create('/var/www/target-project');

// Search by namespace prefix
$results = $classFinder->findByNamespacePrefix('App\\Service');

// Search by partial name (case-insensitive by default)
$results = $classFinder->findByPartialName('User');

// Search by regular expression (on short class name)
$results = $classFinder->findByRegex('/^User/', MatchTargetEnum::SHORT_NAME);

// Search by similarity (Levenshtein distance) on short names
$results = $classFinder->findBySimilarity('UserService', 3);

// Iterate results
foreach ($results as $dto) {
    echo $dto->fqcn . ' => ' . ($dto->path ?? 'not found') . PHP_EOL;
}