Composer Class Map Generator

https://github.com/composer/class-map-generator
Admin
Composer Class Map Generator is a PHP library that provides utilities to scan PHP code and generate...
Tokens:25,632
Snippets:197
Trust Score:9.2
License:MIT
Update:2 days ago
Show doc for...
Tokens:
Raw
### count usage example

Source: https://github.com/composer/class-map-generator

Example of using count() to get the number of mapped classes.

```php
echo count($classMap); // number of mapped classes
```

--------------------------------

### Usage example with setTypeConfig and clean

Source: https://github.com/composer/class-map-generator

Shows how to configure type keywords and clean a PHP file. The example reads a file, creates a cleaner with maxMatches=1 and rawContents=true, then cleans the source, retaining class declarations while stripping strings and comments.

```php
use Composer\ClassMapGenerator\PhpFileCleaner;

PhpFileCleaner::setTypeConfig(['class', 'interface', 'trait']);

$source = file_get_contents('/srv/app/src/Foo.php');
$cleaner = new PhpFileCleaner($source, 1, true);
$clean = $cleaner->clean();
// $clean retains the class declaration but strips strings/comments
```

--------------------------------

### getRawPsrViolations usage example

Source: https://github.com/composer/class-map-generator

Example of iterating over raw PSR violations to display class names and warnings per path.

```php
foreach ($classMap->getRawPsrViolations() as $path => $violations) {
    foreach ($violations as $v) {
        echo $v['className'] . ' in ' . $path . ': ' . $v['warning'] . PHP_EOL;
    }
}
```

--------------------------------

### Install with Composer

Source: https://github.com/composer/class-map-generator/blob/main/README.md

Install the latest version of composer/class-map-generator using Composer. Requires PHP 7.2 or higher.

```bash
composer require composer/class-map-generator
```

--------------------------------

### clearPsrViolationsByPath usage example

Source: https://github.com/composer/class-map-generator

Example of clearing PSR violations for a path prefix.

```php
$classMap->clearPsrViolationsByPath('/srv/app/src/vendor-pkg');
```

--------------------------------

### FileList add method example

Source: https://github.com/composer/class-map-generator

Creates a FileList instance and adds an absolute file path to mark it as scanned.

```php
use Composer\ClassMapGenerator\FileList;

$files = new FileList();
$files->add('/srv/app/src/Foo.php');
```

--------------------------------

### hasClass usage example

Source: https://github.com/composer/class-map-generator

Example of using hasClass to check for a class.

```php
if ($classMap->hasClass('Acme\\Foo')) {
    // ...
}
```

--------------------------------

### getMap() usage example

Source: https://github.com/composer/class-map-generator

Iterates over the class map and prints each symbol and its path.

```php
$classMap = new ClassMap();
foreach ($classMap->getMap() as $symbol => $path) {
    echo $symbol . ' @ ' . $path . PHP_EOL;
}
```

--------------------------------

### getClassMap() Example

Source: https://github.com/composer/class-map-generator

Creates a ClassMapGenerator, scans the 'src' directory, and retrieves the ClassMap instance to access the map.

```php
$generator = new ClassMapGenerator();
$generator->scanPaths('src');
$classMap = $generator->getClassMap();
$map = $classMap->getMap();
```

--------------------------------

### getPsrViolations() usage example

Source: https://github.com/composer/class-map-generator

Writes each PSR violation warning to STDERR.

```php
foreach ($classMap->getPsrViolations() as $warning) {
    fwrite(STDERR, $warning . PHP_EOL);
}
```

--------------------------------

### FileList contains method example

Source: https://github.com/composer/class-map-generator

Tests if a path is already scanned before adding it, avoiding duplicate work.

```php
if (!$files->contains('/srv/app/src/Foo.php')) {
    $files->add('/srv/app/src/Foo.php');
}
```

--------------------------------

### getAmbiguousFolders usage example

Source: https://github.com/composer/class-map-generator

Iterates over ambiguous folder sets, printing each set of paths that differ only by casing, e.g., src/Foo and src/foo which merge on Windows/macOS.

```php
foreach ($classMap->getAmbiguousFolders() as $paths) {
    // e.g. src/Foo and src/foo which merge on Windows/macOS
    echo implode(' vs ', $paths) . PHP_EOL;
}
```

--------------------------------

### FileList sharing across generators example

Source: https://github.com/composer/class-map-generator

Shares a single FileList instance between two ClassMapGenerator instances to avoid duplicate scans across multiple generators. The second scan skips files already recorded.

```php
use Composer\ClassMapGenerator\FileList;
use Composer\ClassMapGenerator\ClassMapGenerator;

$shared = new FileList();

$g1 = new ClassMapGenerator();
$g1->avoidDuplicateScans($shared);
$g1->scanPaths('src'); // adds each scanned file to $shared

// a second pass over the same tree skips everything already recorded:
$g2 = new ClassMapGenerator();
$g2->avoidDuplicateScans($shared);
$g2->scanPaths('src');
```

--------------------------------

### Static one-shot class map generation

Source: https://github.com/composer/class-map-generator

Scans a directory or single file and returns a ClassMap. Iterate over the map to get FQN => file path pairs.

```php
use Composer\ClassMapGenerator\ClassMapGenerator;

$map = ClassMapGenerator::createMap('path/to/scan');
foreach ($map as $symbol => $path) {
    // $symbol is the FQN, $path is the file where it is declared
}
```

--------------------------------

### getAmbiguousClasses usage example

Source: https://github.com/composer/class-map-generator

Iterates over ambiguous classes, printing each symbol and its paths. Also shows how to include test fixtures by passing false, or use a custom filter regex.

```php
foreach ($classMap->getAmbiguousClasses() as $symbol => $paths) {
    // warn the user that $symbol resolves from multiple files
    echo $symbol . ': ' . implode(', ', $paths) . PHP_EOL;
}

// include test fixtures too:
$all = $classMap->getAmbiguousClasses(false);
// or a custom filter:
$all = $classMap->getAmbiguousClasses('{/vendor/}i');
```

--------------------------------

### Get class path with exception handling

Source: https://github.com/composer/class-map-generator

Retrieves the mapped path for a class. Throws \OutOfBoundsException if the class is not in the map; wrap the call in a try-catch to handle missing entries.

```php
try {
    $path = $classMap->getClassPath('Acme\\Controller');
} catch (\OutOfBoundsException $e) {
    // class not in the map
}
```

--------------------------------

### DEFAULT_DUPLICATES_FILTER constant declaration

Source: https://github.com/composer/class-map-generator

Default regex filter for ambiguous results, matching paths containing test, fixture, example, or stub directories. Pass false to include all paths.

```php
private const DEFAULT_DUPLICATES_FILTER = '{(?:^|/)(test|fixture|example|stub)s?/}i';
```

--------------------------------

### getAmbiguousClasses error handling example

Source: https://github.com/composer/class-map-generator

Shows that passing true to getAmbiguousClasses throws an \InvalidArgumentException with the message 'duplicatesFilter should be false or a string with a valid regex, got true.'

```php
try {
    $classMap->getAmbiguousClasses(true);
} catch (\InvalidArgumentException $e) {
    // "duplicatesFilter should be false or a string with a valid regex, got true."
}
```

--------------------------------

### Sort class map alphabetically

Source: https://github.com/composer/class-map-generator

Sorts the class map in place by class name using ksort. Call before retrieving the map to get entries ordered by fully-qualified name.

```php
$classMap->sort();
$map = $classMap->getMap(); // now sorted by FQN
```

--------------------------------

### Constructor signature

Source: https://github.com/composer/class-map-generator

Initializes the cleaner with source contents, max matches, and raw contents flag. The rawContents parameter indicates whether comments are still present and must be skipped.

```php
public function __construct(string $contents, int $maxMatches, bool $rawContents = false)
```

--------------------------------

### ClassMapGenerator::__construct signature

Source: https://github.com/composer/class-map-generator

Constructor accepting an array of file extensions to scan for classes. Defaults to ['php', 'inc']. Each extension is preg_quote'd and joined into the Finder name regex.

```php
public function __construct(array $extensions = ['php', 'inc'])
```

--------------------------------

### Error handling with ClassMapGenerator::createMap

Source: https://github.com/composer/class-map-generator

Shows how to handle a \RuntimeException when the path is not a file, directory, or glob. A single file path is also accepted as input.

```php
use Composer\ClassMapGenerator\ClassMapGenerator;

try {
    // A single file works too; an existing directory or a glob both work.
    $map = ClassMapGenerator::createMap('src/App/Controller/UserController.php');
} catch (\RuntimeException $e) {
    // thrown when $path is not a file, a directory, nor a glob
    error_log('Could not scan: ' . $e->getMessage());
}
```

--------------------------------

### createMap (static)

Source: https://github.com/composer/class-map-generator

Convenience one-shot entry point that creates a new generator, calls scanPaths() with default options, and returns the resulting raw class map. Accepts a directory path, a single file path, a glob, or an array/traversable of SplFileInfo.

```APIDOC
## createMap (static)

### Description
Convenience one-shot entry point: creates a new generator, calls `scanPaths()` with default options (`classmap` autoload, no exclusion), and returns the resulting raw map.

### Method
`ClassMapGenerator::createMap` (static method)

### Signature
```php
public static function createMap($path): array
```

### Parameters
- `$path` (string | \Traversable<\SplFileInfo> | array<\SplFileInfo>) - Required - Path to search (a directory path, a single file path, a glob, or an array/traversable of `SplFileInfo`, e.g. a symfony/finder instance)

### Return
`array<class-string, non-empty-string>` — the class map as a list of paths indexed by class name. This is exactly what `getMap()` on the underlying `ClassMap` returns.

### Throws
`\RuntimeException` when the path (if a string) is neither an existing file nor a directory, nor a glob string. See [errors](../errors.md).

### Request Example
```php
use Composer\ClassMapGenerator\ClassMapGenerator;

$map = ClassMapGenerator::createMap('src');
foreach ($map as $fqn => $path) {
    echo "$fqn => $path\n";
}
```

### Request Example (error handling / file path input)
```php
use Composer\ClassMapGenerator\ClassMapGenerator;

try {
    // A single file works too; an existing directory or a glob both work.
    $map = ClassMapGenerator::createMap('src/App/Controller/UserController.php');
} catch (\RuntimeException $e) {
    // thrown when $path is not a file, a directory, nor a glob
    error_log('Could not scan: ' . $e->getMessage());
}
```
```

--------------------------------

### Stateful generator with diagnostics

Source: https://github.com/composer/class-map-generator

Create a generator, scan multiple paths, then retrieve the ClassMap. Optionally sort and access ambiguous-class and PSR-violation diagnostics.

```php
use Composer\ClassMapGenerator\ClassMapGenerator;

$generator = new ClassMapGenerator;
$generator->scanPaths('path/to/scan');
$generator->scanPaths('path/to/scan2');

$classMap = $generator->getClassMap();
$classMap->sort(); // optional alphabetical ordering

foreach ($classMap->getMap() as $symbol => $path) {
}

foreach ($classMap->getAmbiguousClasses() as $symbol => $paths) {
    // warning: same symbol found in multiple files
}

foreach ($classMap->getPsrViolations() as $warning) {
    // warning: class does not comply with the configured PSR rule
}
```

--------------------------------

### Constructor with custom extensions

Source: https://github.com/composer/class-map-generator

Creates a ClassMapGenerator instance, optionally specifying file extensions to scan. Defaults to ['php', 'inc'] if not provided.

```php
use Composer\ClassMapGenerator\ClassMapGenerator;

// only consider .php files
$g = new ClassMapGenerator(['php']);
// defaults: new ClassMapGenerator(); // {php, inc}
```

--------------------------------

### FileList

Source: https://github.com/composer/class-map-generator

A plain set used as a registry for already-scanned files. Provides add and contains methods.

```APIDOC
## FileList

### Description
A plain set used as a registry for already-scanned files. Provides add and contains methods.

### Methods
- `add(string $path): void`
- `contains(string $path): bool`
```

--------------------------------

### scanPaths() Basic Directory Scan

Source: https://github.com/composer/class-map-generator

Scans multiple directories and outputs the class map entries. Uses sort() before iterating.

```php
use Composer\ClassMapGenerator\ClassMapGenerator;

$g = new ClassMapGenerator();
$g->scanPaths('src');
$g->scanPaths('src/Extra');
$g->getClassMap()->sort();
foreach ($g->getClassMap()->getMap() as $fqn => $path) {
    var_dump($fqn, $path);
}
```

--------------------------------

### Basic usage of ClassMapGenerator::createMap

Source: https://github.com/composer/class-map-generator

Creates a class map for a directory path using default options. The returned map is an array of class names to file paths, which can be iterated to display each mapping.

```php
use Composer\ClassMapGenerator\ClassMapGenerator;

$map = ClassMapGenerator::createMap('src');
foreach ($map as $fqn => $path) {
    echo "$fqn => $path\n";
}
```

--------------------------------

### Create a class map with ClassMapGenerator::createMap

Source: https://github.com/composer/class-map-generator/blob/main/README.md

Scans a directory and returns a class map with all classes, interfaces, traits, and enums mapped to their paths. Iterate over the returned map to access each symbol and its path.

```php
use Composer\ClassMapGenerator\ClassMapGenerator;

$map = ClassMapGenerator::createMap('path/to/scan');
foreach ($map as $symbol => $path) {
    // do your thing
}
```

--------------------------------

### getPsrViolations() method signature

Source: https://github.com/composer/class-map-generator

Returns an array of warning strings describing PSR-0/4 violations. Only produced when paths were scanned with a psr-0/psr-4 autoload type; returns [] when none.

```php
public function getPsrViolations(): array
```

--------------------------------

### ClassMapGenerator::scanPaths signature

Source: https://github.com/composer/class-map-generator

Main scanning method with parameters for path, exclusion regex, autoload type, namespace, and excluded directories. For psr-0/psr-4, $path must be a string and $namespace must be provided.

```php
public function scanPaths($path, ?string $excluded = null, string $autoloadType = 'classmap', ?string $namespace = null, array $excludedDirs = []): void
```

--------------------------------

### FileList add method signature

Source: https://github.com/composer/class-map-generator

Adds a path to the set. Idempotent; marks the path as scanned.

```php
public function add(string $path): void
```

--------------------------------

### PhpFileParser::findClasses - error handling

Source: https://github.com/composer/class-map-generator

Demonstrates catching a RuntimeException thrown by findClasses when the file does not exist. The error message includes the file path and suggests checking classmap definitions.

```php
use Composer\ClassMapGenerator\PhpFileParser;

try {
    $classes = PhpFileParser::findClasses('/path/that/does/not/exist.php');
} catch (\RuntimeException $e) {
    // e.g. 'File at "/path/.../exist.php" does not exist, check your classmap definitions'
    echo $e->getMessage() . PHP_EOL;
}
```

--------------------------------

### ClassMap::getPsrViolations()

Source: https://github.com/composer/class-map-generator

Returns an array of warnings for classes that do not comply with the configured PSR rule. Each warning is a string message.

```APIDOC
## ClassMap::getPsrViolations()

### Description
Returns an array of warnings for classes that do not comply with the configured PSR rule. Each warning is a string message.

### Method
Instance method

### Endpoint
`$classMap->getPsrViolations()`

### Parameters
None

### Return Value
Returns an array of warning strings.

### Request Example
```php
foreach ($classMap->getPsrViolations() as $warning) {
    // warning: class does not comply with the configured PSR rule
}
```
```

--------------------------------

### Advanced usage with generator object and scanPaths

Source: https://github.com/composer/class-map-generator/blob/main/README.md

Instantiate a generator object, call scanPaths one or more times, then getClassMap to obtain a ClassMap object with the resulting map and warnings. Optionally sort classes alphabetically, and iterate over ambiguous classes and folders to warn users about resolution issues.

```php
use Composer\ClassMapGenerator\ClassMapGenerator;

$generator = new ClassMapGenerator;
$generator->scanPaths('path/to/scan');
$generator->scanPaths('path/to/scan2');

$classMap = $generator->getClassMap();
$classMap->sort(); // optionally sort classes alphabetically
foreach ($classMap->getMap() as $symbol => $path) {
    // do your thing
}

foreach ($classMap->getAmbiguousClasses() as $symbol => $paths) {
    // warn user about ambiguous class resolution
}

foreach ($classMap->getAmbiguousFolders() as $paths) {
    // warn user that these paths only differ in casing, and therefore fold into a
    // single file/folder on case insensitive filesystems like those of Windows/macOS
}
```

--------------------------------

### setTypeConfig static method signature

Source: https://github.com/composer/class-map-generator

Configures the static key-type lookup used while cleaning. Precomputes keyword length and per-character regex for each type, and builds the $rejectChars string of characters that terminate a run of clean code.

```php
public static function setTypeConfig(array $types): void
```

--------------------------------

### getRawPsrViolations method signature

Source: https://github.com/composer/class-map-generator

Returns raw PSR violations as a map of file path to list of {warning, className} entries. Unlike getPsrViolations(), this preserves per-path grouping and offending class names.

```php
public function getRawPsrViolations(): array
```

--------------------------------

### ClassMapGenerator::createMap()

Source: https://github.com/composer/class-map-generator

Static convenience method that scans a directory or file and returns a ClassMap. It is the primary one-shot entry point for generating a class map.

```APIDOC
## ClassMapGenerator::createMap()

### Description
Static convenience method that scans a directory or file and returns a ClassMap. It is the primary one-shot entry point for generating a class map.

### Method
Static method

### Endpoint
`ClassMapGenerator::createMap(string $path)`

### Parameters
- **$path** (string) - Required - Path to a directory or file to scan.

### Return Value
Returns a `ClassMap` object containing the generated class map.

### Request Example
```php
use Composer\ClassMapGenerator\ClassMapGenerator;

$map = ClassMapGenerator::createMap('path/to/scan');
foreach ($map as $symbol => $path) {
    // $symbol is the FQN, $path is the file where it is declared
}
```
```

--------------------------------

### getPsrViolations

Source: https://github.com/composer/class-map-generator

Returns an array of warning strings describing PSR-0/4 violations detected during scanning. Only produced when paths were scanned with a psr-0/psr-4 autoload type; returns an empty array when there are none.

```APIDOC
## getPsrViolations

### Description
Returns an array of warning strings describing PSR-0/4 violations detected during scanning.

### Method
GET

### Endpoint
ClassMap::getPsrViolations()

### Parameters
None

### Response
#### Success Response (200)
- **array** (string[]) - Warning strings describing PSR-0/4 violations.

### Request Example
```php
foreach ($classMap->getPsrViolations() as $warning) {
    fwrite(STDERR, $warning . PHP_EOL);
}
```
```

--------------------------------

### ClassMapGenerator::__construct

Source: https://github.com/composer/class-map-generator

Constructor for the ClassMapGenerator class. Accepts an optional array of file extensions to scan for classes.

```APIDOC
## ClassMapGenerator::__construct

### Description
Constructor for the ClassMapGenerator class. Accepts an optional array of file extensions to scan for classes.

### Method
Constructor

### Signature
```php
public function __construct(array $extensions = ['php', 'inc'])
```

### Parameters
- **$extensions** (array of strings) - Optional - File extensions scanned for classes. Each entry is `preg_quote`'d and joined into the Finder name regex `'/\\.(?:ext1|ext2|...)$/'`.
```

--------------------------------

### count method signature

Source: https://github.com/composer/class-map-generator

Returns the number of entries in the map. Makes the object usable with count() via \Countable.

```php
public function count(): int
```

--------------------------------

### getRawPsrViolations

Source: https://github.com/composer/class-map-generator

Returns the raw PSR violations as a map of file path to list of `{warning, className}` entries. Unlike `getPsrViolations()`, this preserves the per-path grouping and the offending class names.

```APIDOC
## getRawPsrViolations

### Description
Returns the raw PSR violations as a map of file path to list of `{warning, className}` entries. Unlike `getPsrViolations()`, this preserves the per-path grouping and the offending class names.

### Method
`getRawPsrViolations`

### Signature
```php
public function getRawPsrViolations(): array
```

### Return Type
`array<string, array<array{warning: string, className: string}>>` — the raw PSR violations as a map of file path → list of `{warning, className}` entries.

### Example
```php
foreach ($classMap->getRawPsrViolations() as $path => $violations) {
    foreach ($violations as $v) {
        echo $v['className'] . ' in ' . $path . ': ' . $v['warning'] . PHP_EOL;
    }
}
```
```

--------------------------------

### clean method signature

Source: https://github.com/composer/class-map-generator

Returns the cleaned source with PHP open tags preserved, strings and heredocs replaced with null, comments stripped, and class/interface/trait declarations intact. Can return early when maxMatches equals 1.

```php
public function clean(): string
```

--------------------------------

### getMap() method signature

Source: https://github.com/composer/class-map-generator

Returns the class map as an array of paths indexed by class name.

```php
public function getMap(): array
```

--------------------------------

### add

Source: https://github.com/composer/class-map-generator

Adds a path to the set of scanned files. This method is idempotent, meaning adding the same path multiple times has no additional effect.

```APIDOC
## add

### Description
Adds the path to the set (idempotent).

### Method
`public function add(string $path): void`

### Parameters
- `$path` (non-empty-string) - Required - Absolute path to mark as scanned.

### Example
```php
use Composer\ClassMapGenerator\FileList;

$files = new FileList();
$files->add('/srv/app/src/Foo.php');
```
```

--------------------------------

### scanPaths($path, ?string $excluded = null, string $autoloadType = 'classmap', ?string $namespace = null, array $excludedDirs = []): void

Source: https://github.com/composer/class-map-generator

Scans the given path(s) for classes and adds them to the classmap. Supports classmap, PSR-0, and PSR-4 autoload standards with optional namespace filtering and directory exclusions.

```APIDOC
## scanPaths($path, ?string $excluded = null, string $autoloadType = 'classmap', ?string $namespace = null, array $excludedDirs = []): void

### Description
Scans the given path(s) for classes and adds them to the classmap. Supports classmap, PSR-0, and PSR-4 autoload standards with optional namespace filtering and directory exclusions.

### Method
GET

### Endpoint
`scanPaths($path, ?string $excluded = null, string $autoloadType = 'classmap', ?string $namespace = null, array $excludedDirs = []): void`

### Parameters
#### Path Parameters
- **$path** (string | \Traversable<\SplFileInfo> | array<\SplFileInfo>) - Required - The path to search in, or an array/traversable of `SplFileInfo` (e.g. a symfony/finder instance). If a string and it is a file it is scanned alone; if a directory or contains `*` it is scanned through a `Finder`; otherwise `\RuntimeException` is thrown.

#### Query Parameters
- **$excluded** (?string) - Optional - A regex that matches file paths to be excluded from the classmap. Tested against both the realpath and the raw path of each file.
- **$autoloadType** ('classmap' | 'psr-0' | 'psr-4') - Optional - Autoload standard. `classmap` collects all classes; `psr-0`/`psr-4` apply namespace mapping rules and record violations.
- **$namespace** (?string) - Optional - Namespace prefix to filter by; only used for `psr-0`/`psr-4`.
- **$excludedDirs** (array<string>) - Optional - Directories to exclude from the search, relative to `$path`.

### Response
#### Success Response
- **void** - No return value.

### Request Example
```php
use Composer\ClassMapGenerator\ClassMapGenerator;

$g = new ClassMapGenerator();
$g->scanPaths('src');
$g->scanPaths('src/Extra');
$g->getClassMap()->sort();
foreach ($g->getClassMap()->getMap() as $fqn => $path) {
    var_dump($fqn, $path);
}
```

### Request Example
```php
use Composer\ClassMapGenerator\ClassMapGenerator;

$g = new ClassMapGenerator();
$g->avoidDuplicateScans();

$g->scanPaths(
    __DIR__ . '/packages/foo/src',
    excluded: '{/vendor/}',
    autoloadType: 'psr-4',
    namespace: 'Acme\\Foo\\',
    excludedDirs: ['Tests', 'Fixtures']
);

$cm = $g->getClassMap();
foreach ($cm->getPsrViolations() as $warning) {
    // classes that would not autoload under the PSR-4 mapping
    fwrite(STDERR, $warning . "\n");
}
```
```

--------------------------------

### scanPaths() PSR-4 Rule with Namespace Filter and Exclusions

Source: https://github.com/composer/class-map-generator

Scans a PSR-4 directory with a namespace filter, exclusions, and excluded directories. Prints PSR violations to STDERR.

```php
use Composer\ClassMapGenerator\ClassMapGenerator;

$g = new ClassMapGenerator();
$g->avoidDuplicateScans();

$g->scanPaths(
    __DIR__ . '/packages/foo/src',
    excluded: '{/vendor/}',
    autoloadType: 'psr-4',
    namespace: 'Acme\\Foo\\',
    excludedDirs: ['Tests', 'Fixtures']
);

$cm = $g->getClassMap();
foreach ($cm->getPsrViolations() as $warning) {
    // classes that would not autoload under the PSR-4 mapping
    fwrite(STDERR, $warning . "\n");
}
```

--------------------------------

### ClassMapGenerator::avoidDuplicateScans signature

Source: https://github.com/composer/class-map-generator

Enables duplicate scan avoidance by providing a FileList registry. When set, scanPaths() skips files already in the list.

```php
public function avoidDuplicateScans(?FileList $scannedFiles = null): self
```

--------------------------------

### new ClassMapGenerator(array $extensions = ['php', 'inc'])

Source: https://github.com/composer/class-map-generator

Constructor for the ClassMapGenerator facade. Initializes an empty private ClassMap and builds a streamWrappersRegex from stream_get_wrappers() to detect stream wrapper paths such as phar://.

```APIDOC
## Constructor

### Description
Initializes a new ClassMapGenerator instance with optional file extensions to scan for classes.

### Method
Constructor

### Endpoint
`Composer\ClassMapGenerator\ClassMapGenerator::__construct`

### Parameters
#### Constructor Parameters
- **$extensions** (array, list<string>) - Optional - Default: `['php', 'inc']` - File extensions to scan for classes in the given paths

### Example
```php
use Composer\ClassMapGenerator\ClassMapGenerator;

// only consider .php files
$g = new ClassMapGenerator(['php']);
// defaults: new ClassMapGenerator(); // {php, inc}
```
```

--------------------------------

### Catch exceptions from ClassMapGenerator::createMap()

Source: https://github.com/composer/class-map-generator

Shows how to catch RuntimeException and InvalidArgumentException when calling createMap() with an invalid path or invalid autoload type. The RuntimeException covers path-not-found and file-level parse failures; InvalidArgumentException covers invalid $autoloadType or psr path/namespace requirements.

```php
use Composer\ClassMapGenerator\ClassMapGenerator;

try {
    $map = ClassMapGenerator::createMap('/missing/path');
} catch (\RuntimeException $e) {
    // path is not a file/or/dir/glob (case 1), or file-level parse failures propagate here
    echo $e->getMessage();
} catch (\InvalidArgumentException $e) {
    // invalid $autoloadType / psr path & namespace requirements
}
```

--------------------------------

### addPsrViolation method signature

Source: https://github.com/composer/class-map-generator

Records a PSR violation for a given path. Used by the generator's filterByNamespace().

```php
public function addPsrViolation(string $warning, string $className, string $path): void
```

--------------------------------

### avoidDuplicateScans with optional FileList

Source: https://github.com/composer/class-map-generator

Enables duplicate scan avoidance. Pass a FileList to share across generators, or omit to use a fresh internal one.

```php
use Composer\ClassMapGenerator\ClassMapGenerator;
use Composer\ClassMapGenerator\FileList;

$generator = new ClassMapGenerator();
$generator->avoidDuplicateScans(); // use a fresh internal FileList
// or share your own registry across generators:
$generator->avoidDuplicateScans(new FileList());
```

--------------------------------

### ClassMap::sort()

Source: https://github.com/composer/class-map-generator

Sorts the class map alphabetically by class name. Optional but recommended for deterministic output.

```APIDOC
## ClassMap::sort()

### Description
Sorts the class map alphabetically by class name. Optional but recommended for deterministic output.

### Method
Instance method

### Endpoint
`$classMap->sort()`

### Parameters
None

### Return Value
Returns `void` (modifies the map in place).

### Request Example
```php
$classMap->sort(); // optional alphabetical ordering
```
```

--------------------------------

### findClasses (static)

Source: https://github.com/composer/class-map-generator

Extracts all declared class-like symbol names (classes, interfaces, traits, and enums) from a single PHP source file. Returns the fully-qualified names in declaration order.

```APIDOC
## findClasses (static)

### Description
Extracts all declared class-like symbol names (classes, interfaces, traits, and enums) from a single PHP source file. Returns the fully-qualified names in declaration order.

### Method
Static method

### Signature
```php
public static function findClasses(string $path): array
```

### Parameters
- `$path` (string) - Required - The file to check.

### Return
`list<class-string>` - The fully-qualified names of the classes, interfaces, traits, and enums found in the file, in declaration order.

### Throws
`RuntimeException` in several conditions. See [errors](../errors.md).

### Behavior
1. Reads the raw file via `file_get_contents()` and, when it succeeds and is non-empty, uses the *raw* source (so `#`/`//` comments are still present and must be skipped by the cleaner). Otherwise falls back to `php_strip_whitespace()`. If `php_strip_whitespace` does not exist, throws.
2. If the content is empty/missing/blank, throws `RuntimeException` with one of these messages: file does not exist, not readable, really empty (returns `[]` for semantically empty files), or could not be parsed as PHP (binary or corrupted). When an earlier warning exists, it is appended via `error_get_last()`.
3. Regex-pre-screens for `class|interface|trait` (+ `enum`) and returns `[]` early if none are present.
4. Feeds the (already-`php_strip_whitespace`-processed or raw) contents through `PhpFileCleaner`, then runs the main symbol-matching regex.
5. Namespaces are tracked as they appear; anonymous classes extending / implementing (`extends`/`implements` as the captured name) are skipped.
6. XHP classes are prefixed with `xhp` and `-`/`:` are translated to `_`/`__`.
7. For enums, a trailing `: <backed-type>` captured by the regex is stripped from the name.

### Request Example
```php
use Composer\ClassMapGenerator\PhpFileParser;

$classes = PhpFileParser::findClasses(__DIR__ . '/src/App/Controller.php');
foreach ($classes as $fqn) {
    echo $fqn . PHP_EOL;
}
```

### Response Example
```php
use Composer\ClassMapGenerator\PhpFileParser;

try {
    $classes = PhpFileParser::findClasses('/path/that/does/not/exist.php');
} catch (\RuntimeException $e) {
    // e.g. 'File at "/path/.../exist.php" does not exist, check your classmap definitions'
    echo $e->getMessage() . PHP_EOL;
}
```
```

--------------------------------

### ClassMapGenerator::avoidDuplicateScans

Source: https://github.com/composer/class-map-generator

Enables duplicate scan avoidance by providing a FileList registry of already-scanned paths.

```APIDOC
## ClassMapGenerator::avoidDuplicateScans

### Description
Enables duplicate scan avoidance by providing a FileList registry of already-scanned paths.

### Method
Method

### Signature
```php
public function avoidDuplicateScans(?FileList $scannedFiles = null): self
```

### Parameters
- **$scannedFiles** (?FileList) - Optional - Registry of already-scanned absolute paths; when set, `scanPaths()` skips any file it already contains.
```

--------------------------------

### ClassMapGenerator::scanPaths

Source: https://github.com/composer/class-map-generator

Scans a path or iterable of files for classes. Supports different autoload types and exclusion options.

```APIDOC
## ClassMapGenerator::scanPaths

### Description
Scans a path or iterable of files for classes. Supports different autoload types and exclusion options.

### Method
Method

### Signature
```php
public function scanPaths($path, ?string $excluded = null, string $autoloadType = 'classmap', ?string $namespace = null, array $excludedDirs = []): void
```

### Parameters
- **$path** (string|Traversable|array) - Required - Source to scan: directory path, single file path, glob, or a finder/iterable of `SplFileInfo`.
- **$excluded** (?string) - Optional - Regex matched against each file's realpath and raw path; matching files are skipped. If `null`, nothing is excluded.
- **$autoloadType** ('classmap'|'psr-0'|'psr-4') - Optional - Rule type. `classmap` collects every class found. `psr-0`/`psr-4` filter by namespace mapping and record violations; then `$path` must be a `string` and `$namespace` must be provided.
- **$namespace** (?string) - Optional - Namespace prefix for `psr-0`/`psr-4` filtering. May be an empty string `''` to disable filtering while still enforcing the standard.
- **$excludedDirs** (array of strings) - Optional - Directories excluded from the Finder search, relative to `$path`.
```

--------------------------------

### getAmbiguousFolders

Source: https://github.com/composer/class-map-generator

Returns sets of paths that are identical except for casing, which can cause issues on case-insensitive filesystems. The optional filter can exclude paths matching a regex, or false to include all paths.

```APIDOC
## getAmbiguousFolders

### Description
Returns sets of paths that are identical except for casing, which can cause issues on case-insensitive filesystems. The optional filter can exclude paths matching a regex, or false to include all paths.

### Method
PHP method

### Signature
`public function getAmbiguousFolders($duplicatesFilter = self::DEFAULT_DUPLICATES_FILTER): array`

### Parameters
- `$duplicatesFilter` (non-empty-string | false) - Optional - Same semantics as `getAmbiguousClasses()`. Default: `'{(?:^|/)(test|fixture|example|stub)s?/}i'`. Passing `true` throws `\InvalidArgumentException`.

### Return
`list<non-empty-list<non-empty-string>>` - Sets of paths that are identical except for casing.

### Request Example
```php
foreach ($classMap->getAmbiguousFolders() as $paths) {
    // e.g. src/Foo and src/foo which merge on Windows/macOS
    echo implode(' vs ', $paths) . PHP_EOL;
}
```
```

--------------------------------

### Add class to map with addClass

Source: https://github.com/composer/class-map-generator

Adds a class-to-path mapping, clears any PSR violation for that path, and invalidates the ambiguous-folders cache. The path must be a non-empty string.

```php
$classMap->addClass('Acme\\Foo', '/srv/app/src/foo.php');
echo $classMap->getClassPath('Acme\\Foo'); // /srv/app/src/foo.php
```

--------------------------------

### avoidDuplicateScans(?FileList $scannedFiles = null): self

Source: https://github.com/composer/class-map-generator

Enables duplicate scan avoidance. When set, repeated scanPaths() calls will skip any absolute file path already present in the list, so the same class is never scanned twice and duplicate PSR warnings are not re-emitted.

```APIDOC
## avoidDuplicateScans

### Description
Enables duplicate scan avoidance. When set, repeated scanPaths() calls will skip any absolute file path already present in the list, so the same class is never scanned twice and duplicate PSR warnings are not re-emitted. This matters when paths may overlap between calls.

### Method
Method

### Endpoint
`Composer\ClassMapGenerator\ClassMapGenerator::avoidDuplicateScans`

### Parameters
#### Method Parameters
- **$scannedFiles** (?FileList) - Optional - Default: `null` (a new `FileList` is created) - Optional user-supplied file registry

### Returns
- **$this** (self) - Fluent interface

### Example
```php
use Composer\ClassMapGenerator\ClassMapGenerator;
use Composer\ClassMapGenerator\FileList;

$generator = new ClassMapGenerator();
$generator->avoidDuplicateScans(); // use a fresh internal FileList
// or share your own registry across generators:
$generator->avoidDuplicateScans(new FileList());
```
```

--------------------------------

### ClassMap properties: $map

Source: https://github.com/composer/class-map-generator

Public raw map property: fully-qualified class name to file path. Read/write accessible directly, though accessor methods are preferred.

```php
/**
 * @var array<class-string, non-empty-string>
 */
public $map = [];
```

--------------------------------

### addPsrViolation

Source: https://github.com/composer/class-map-generator

Records a PSR violation for a given path. This is a write-side method used by the generator's filterByNamespace().

```APIDOC
## addPsrViolation

### Description
Records a PSR violation for the given path. Write-side method used by the generator's `filterByNamespace()`.

### Method
`addPsrViolation`

### Parameters
- `$warning` (string) - Required - Human-readable warning message.
- `$className` (string) - Required - The offending class name.
- `$path` (string) - Required - The file path; normalized (trailing slash removed, backslashes → slashes) and used as the grouping key.

### Return
`void`
```

--------------------------------

### ClassMapGenerator::avoidDuplicateScans()

Source: https://github.com/composer/class-map-generator

Enables duplicate scan avoidance by having the generator own a FileList that tracks already-scanned absolute file paths. This is an opt-in feature.

```APIDOC
## ClassMapGenerator::avoidDuplicateScans()

### Description
Enables duplicate scan avoidance by having the generator own a FileList that tracks already-scanned absolute file paths. This is an opt-in feature.

### Method
Instance method

### Endpoint
`$generator->avoidDuplicateScans()`

### Parameters
None

### Return Value
Returns `void` (enables the feature).
```

--------------------------------

### ClassMap::getMap()

Source: https://github.com/composer/class-map-generator

Returns the associative array mapping fully-qualified class names to file paths. This is the primary read method for the generated class map.

```APIDOC
## ClassMap::getMap()

### Description
Returns the associative array mapping fully-qualified class names to file paths. This is the primary read method for the generated class map.

### Method
Instance method

### Endpoint
`$classMap->getMap()`

### Parameters
None

### Return Value
Returns an array of `symbol => path` pairs.

### Request Example
```php
foreach ($classMap->getMap() as $symbol => $path) {
}
```
```

--------------------------------

### ClassMap::getAmbiguousClasses and getAmbiguousFolders signatures

Source: https://github.com/composer/class-map-generator

Methods to retrieve ambiguous classes or folders with an optional filter. Passing true throws \InvalidArgumentException.

```php
public function getAmbiguousClasses($duplicatesFilter = self::DEFAULT_DUPLICATES_FILTER): array
```

```php
public function getAmbiguousFolders($duplicatesFilter = self::DEFAULT_DUPLICATES_FILTER): array
```

--------------------------------

### getMap

Source: https://github.com/composer/class-map-generator

Returns the class map: an array of fully-qualified class names mapped to file paths. This is the primary accessor for the map data.

```APIDOC
## getMap

### Description
Returns the class map: an array of fully-qualified class names mapped to file paths.

### Method
GET

### Endpoint
ClassMap::getMap()

### Parameters
None

### Response
#### Success Response (200)
- **array** (array<class-string, non-empty-string>) - The class map: a list of paths indexed by class name.

### Request Example
```php
$classMap = new ClassMap();
foreach ($classMap->getMap() as $symbol => $path) {
    echo $symbol . ' @ ' . $path . PHP_EOL;
}
```
```

--------------------------------

### FileList contains method signature

Source: https://github.com/composer/class-map-generator

Checks whether a path is already registered as scanned. Returns true if the path is in the set.

```php
public function contains(string $path): bool
```

--------------------------------

### count

Source: https://github.com/composer/class-map-generator

Returns the number of entries in the map. Makes the object usable with `count()` via `\Countable`.

```APIDOC
## count

### Description
Returns the number of entries in the map. Makes the object usable with `count()` via `\Countable`.

### Method
`count`

### Signature
```php
public function count(): int
```

### Return Type
`int` — the number of entries in the map.

### Example
```php
echo count($classMap); // number of mapped classes
```
```

--------------------------------

### ClassMap::getRawPsrViolations()

Source: https://github.com/composer/class-map-generator

Returns raw PSR violation data. The exact structure is not detailed in the source.

```APIDOC
## ClassMap::getRawPsrViolations()

### Description
Returns raw PSR violation data. The exact structure is not detailed in the source.

### Method
Instance method

### Endpoint
`$classMap->getRawPsrViolations()`

### Parameters
None

### Return Value
Returns raw PSR violation data.
```

--------------------------------

### PhpFileParser::findClasses()

Source: https://github.com/composer/class-map-generator

Static method that extracts class names from a PHP file. It uses php_strip_whitespace() with a fallback to PhpFileCleaner for tokenization.

```APIDOC
## PhpFileParser::findClasses()

### Description
Static method that extracts class names from a PHP file. It uses php_strip_whitespace() with a fallback to PhpFileCleaner for tokenization.

### Method
Static method

### Endpoint
`PhpFileParser::findClasses(string $file)`

### Parameters
- **$file** (string) - Required - Path to the PHP file to parse.

### Return Value
Returns an array of fully-qualified class names found in the file.
```

--------------------------------

### ClassMap::getAmbiguousFolders()

Source: https://github.com/composer/class-map-generator

Returns an array of ambiguous folder diagnostics. The exact structure is not detailed in the source.

```APIDOC
## ClassMap::getAmbiguousFolders()

### Description
Returns an array of ambiguous folder diagnostics. The exact structure is not detailed in the source.

### Method
Instance method

### Endpoint
`$classMap->getAmbiguousFolders()`

### Parameters
None

### Return Value
Returns an array of ambiguous folder diagnostics.
```

--------------------------------

### getClassPath

Source: https://github.com/composer/class-map-generator

Returns the file path associated with a given class name. Throws an OutOfBoundsException if the class is not present in the map.

```APIDOC
## getClassPath

### Description
Returns the path the class is mapped to. Throws an OutOfBoundsException when the class is not present in the map.

### Method
`getClassPath`

### Signature
```php
public function getClassPath(string $className): string
```

### Parameters
#### Parameters
- **$className** (`class-string` (`string`)) - Required - The fully-qualified class name.

### Return Value
`non-empty-string` - The path the class is mapped to.

### Throws
- `\OutOfBoundsException` - When the class is not present in the map.

### Example
```php
try {
    $path = $classMap->getClassPath('Acme\\Controller');
} catch (\OutOfBoundsException $e) {
    // class not in the map
}
```
```

--------------------------------

### ClassMap::getAmbiguousClasses / getAmbiguousFolders

Source: https://github.com/composer/class-map-generator

Retrieve ambiguous classes or folders with an optional filter to exclude paths matching a regex.

```APIDOC
## ClassMap::getAmbiguousClasses / getAmbiguousFolders

### Description
Retrieve ambiguous classes or folders with an optional filter to exclude paths matching a regex.

### Method
Method

### Signatures
```php
public function getAmbiguousClasses($duplicatesFilter = self::DEFAULT_DUPLICATES_FILTER): array
public function getAmbiguousFolders($duplicatesFilter = self::DEFAULT_DUPLICATES_FILTER): array
```

### Parameters
- **$duplicatesFilter** (non-empty-string|false) - Optional - Case-insensitive regex; paths it matches are omitted from the ambiguous results. Pass `false` to include all paths. Passing `true` throws `\InvalidArgumentException`.
```
Tokens:
Raw