README

A minimal PHP 8.3+ library for deterministic class discovery and validation.

What it does

• Uses liquidrazor/file-locator to discover PHP files
• Maps file paths → FQCN using PSR-4 rules
• Validates that your codebase matches its declared structure
• Exposes structural symbol metadata from declared symbols when declaration validation runs

That’s it.

Philosophy

• Filesystem is truth
• Deterministic mapping over guesswork
• Validation is explicit, not implicit
• No magic, no hidden loading
• Built for real-world broken projects

Dependency Model

ClassLocator is built on top of:

• liquidrazor/file-locator

It does NOT define roots.
It consumes whatever FileLocator provides.

Namespace Resolution

ClassLocator does NOT detect namespaces for discovery.

Instead:

1. Namespace roots are loaded from the target project's composer.json (PSR-4)
2. File paths are mapped deterministically to expected FQCN
3. Namespace parsing is used for validation and structural metadata extraction when enabled by mode

Filesystem + Composer define expectation.
Files must comply.

Modes

ENFORCING (default)

• Requires valid Composer PSR-4 mappings
• Validates all files
• Extracts structural metadata from declared symbols
• Throws on critical violations
• Fails fast on broken structure

STRICT

• Validates all files
• Extracts structural metadata from declared symbols
• Collects violations
• Does not throw

LENIENT

• Best-effort discovery
• Skips invalid entries
• Skips declaration validation
• Returns unresolved structural metadata instead of guessing

Validation

Validation compares:

expected (path + composer)
vs
actual (file namespace + symbol)

Detects:

• Namespace mismatch
• Class/interface/trait/enum mismatch
• Files outside PSR-4 scope
• Duplicate FQCN
• Missing or invalid Composer mappings

Usage

$fileLocator = new FileLocator(...);

$classLocator = new ClassLocator($fileLocator, Mode::STRICT);

$result = $classLocator->locate();

Public API

ClassLocator

new ClassLocator(FileLocator $fileLocator, Mode $mode = Mode::ENFORCING)

LocateResult locate()

Mode (enum)

Mode::ENFORCING
Mode::STRICT
Mode::LENIENT

LocateResult

array getClasses()
array getViolations()
bool hasViolations()

SymbolKind (enum)

SymbolKind::CLASS_
SymbolKind::INTERFACE
SymbolKind::TRAIT
SymbolKind::ENUM

SymbolKind::CLASS_ uses a trailing underscore because CLASS collides with PHP's ::class constant syntax.

ClassInfo

string getFqcn()
string getPath()
?SymbolKind getSymbolKind()
array getImplementedInterfaces()
?string getParentClass()
?bool isAbstract()
?bool isFinal()
bool hasResolvedMetadata()

In ENFORCING and STRICT, ClassInfo metadata is derived from the declared symbol in the source file.

In LENIENT, declaration parsing is skipped, so:

• getSymbolKind() returns null
• getImplementedInterfaces() returns []
• getParentClass() returns null
• isAbstract() returns null
• isFinal() returns null
• hasResolvedMetadata() returns false

Violation

string getMessage()
string getPath()

Example: Inspect Structural Metadata

$fileLocator = new FileLocator(...);
$classLocator = new ClassLocator($fileLocator, Mode::STRICT);

$result = $classLocator->locate();

foreach ($result->getClasses() as $classInfo) {
    if (!$classInfo->hasResolvedMetadata()) {
        continue;
    }

    if ($classInfo->getSymbolKind() !== SymbolKind::CLASS_) {
        continue;
    }

    if (in_array('App\\Contract\\EventSubscriber', $classInfo->getImplementedInterfaces(), true)) {
        // Downstream code can classify this symbol without re-parsing the file.
    }
}

Responsibility Boundary

ClassLocator exposes structural symbol metadata.

It still does NOT:

• classify framework concepts
• register services
• detect event semantics
• manipulate autoloading
• execute discovered files

Downstream tools may use the exposed metadata for their own classification or validation logic.

Summary

Give it a FileLocator.

It gives you deterministic classes, structural violations, and source-derived symbol metadata when validation is enabled.