adachsoft/static-class-finder

A robust, standalone PHP library that resolves the file path of a class based on its Fully Qualified Class Name (FQCN) using only static Composer maps.

v0.2.0 2026-06-02 21:01 UTC

Requires

• php: ^8.3
• adachsoft/collection: ^3.0

Requires (Dev)

• adachsoft/php-code-style: ^0.4
• friendsofphp/php-cs-fixer: ^3.94.2
• phpstan/phpstan: ^2.1.44
• phpunit/phpunit: ^13.0.5
• rector/rector: ^2.3.9

MIT

• Arkadiusz Adach

• autoloader
• psr-0
• composer
• locator
• PSR-4
• static-analysis
• class-finder

README

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

• No Reflection: Does not load or execute the target class. Safe for files with syntax errors.
• Lightweight Dependencies: Requires PHP 8.3+ and one runtime dependency (adachsoft/collection).
• Composer Compatible: Supports classmap, psr-4, and psr-0 (legacy).
• Lazy Loading: Loads Composer maps only when necessary.
• Advanced Searching: Search classes by namespace prefix, partial name, regex, or Levenshtein similarity.

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;
}