Pest Plugin Arch

https://github.com/pestphp/pest-plugin-arch
Admin
Pest Plugin Arch is a plugin for the Pest testing framework that allows for architectural testing of...
Tokens:34,539
Snippets:523
Trust Score:9.6
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install development dependencies

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/CONTRIBUTING.md

Run this command after cloning the repository to install all required dependencies.

```bash
composer install
```

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

### Creating an ObjectDescription

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/10-errors-and-objects.md

Example usage of the make method to analyze a specific file and iterate through its dependencies.

```php
$obj = ObjectDescription::make('src/Models/User.php');
if ($obj) {
    echo $obj->name; // 'App\Models\User'
    foreach ($obj->uses as $use) {
        echo $use; // List of used classes and functions
    }
}
```

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

### CLI Argument Transformation Examples

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/11-plugin-and-architectable.md

Examples showing how --arch and --exclude-arch flags are internally mapped to group arguments.

```php
// CLI: pest --arch
// Internally converted to: pest --group=arch

// CLI: pest --exclude-arch
// Internally converted to: pest --exclude-group=arch
```

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

### Verify plugin installation

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Commands to check plugin registration and resolve installation issues.

```bash
# Verify plugin is registered
composer show pestphp/pest-plugin-arch

# Clear Composer cache
composer clear-cache

# Reinstall
composer install --no-cache
```

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

### Creating Layers with LayerFactory

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/07-collections-and-factories.md

Examples of creating layers using exact namespaces, wildcards, and filtering.

```php
$factory = new LayerFactory($repository);

// Simple namespace
$layer = $factory->make($options, 'App\Services');

// Wildcard pattern
$layer = $factory->make($options, 'App\Controllers\*');

// With filtering
$layer = $factory->make($options, 'App\Models', true);
```

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

### Complete Architecture Test Setup

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/11-plugin-and-architectable.md

Demonstrates shared configuration and specific expectation-based ignores for complex architecture testing.

```php
<?php

use Pest\Arch\Options\TestCaseOptions;

beforeEach(function () {
    // Configure shared ignores
    test()->arch()
        ->ignore('App\Models\Casts')
        ->ignore('App\Models\Factories')
        ->ignoreGlobalFunctions();
});

// Multiple architecture tests
arch('services are final')
    ->expect('App\Services')
    ->classes
    ->toBeFinal();

arch('services only use repositories and contracts')
    ->expect('App\Services')
    ->toOnlyUse([
        'App\Repositories',
        'App\Contracts',
        'Illuminate\Support',
    ]);

arch('repositories are not used outside services')
    ->expect('App\Repositories')
    ->toBeUsedIn('App\Services');

// Add expectation-specific ignores
arch('models can use what they need')
    ->expect('App\Models')
    ->toUse([
        'Illuminate\Database\Eloquent\Model',
        'App\Database',
    ])
    ->ignoring('App\Models\Concerns\HasUuid');
```

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

### Creating a FunctionDescription

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/10-errors-and-objects.md

Example usage of the make method to create a description for a global function.

```php
$fn = FunctionDescription::make('App\Helpers\formatDate');
echo $fn->name; // 'App\Helpers\formatDate'
echo $fn->path; // File path from reflection
```

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

### Using toCollisionEditor

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/10-errors-and-objects.md

Example of converting an exception to a frame for IDE navigation.

```php
$exception = new ArchExpectationFailedException($violation, "...");
$frame = $exception->toCollisionEditor();
// IDE will open src/Models/User.php at line 42
```

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

### CI/CD Pipeline Configurations

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Integration examples for running architecture tests within automated CI/CD pipelines.

```yaml
name: Architecture Tests

on: [push, pull_request]

jobs:
  architecture:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          extensions: mbstring, intl
      
      - name: Install dependencies
        run: composer install --prefer-dist --no-progress
      
      - name: Run architecture tests
        run: vendor/bin/pest --arch
```

```yaml
architecture:
  image: php:8.4
  script:
    - composer install --prefer-dist --no-progress
    - vendor/bin/pest --arch
```

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

### Install Pest Architecture Plugin

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/14-quick-reference.md

Use Composer to add the plugin to your project dependencies.

```bash
composer require pestphp/pest-plugin-arch
```

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

### Using Arch Options in Tests

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/11-plugin-and-architectable.md

Examples of configuring architecture test options within a test case using the arch method.

```php
// In a test
test()->arch()->ignore('App\Models\Concerns');
test()->arch()->ignore(['App\Traits', 'App\Enums']);
test()->arch()->ignoreGlobalFunctions();
```

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

### Access ObjectDescription Properties

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/13-types-reference.md

Example usage for accessing properties of an ObjectDescription instance.

```php
$object->name;              // 'App\Models\User'
$object->path;              // '/project/src/Models/User.php'
$object->uses;              // ObjectUses collection
$object->reflectionClass;   // ReflectionClass for the class
```

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

### Configure TestCaseOptions

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/08-options-and-repositories.md

Use TestCaseOptions to define global ignore rules for namespaces or functions during test setup.

```php
use Pest\Arch\Options\TestCaseOptions;

// At test case setup
$options = new TestCaseOptions();
$options
    ->ignore('App\Models\Casts')
    ->ignore('App\Models\Factories')
    ->ignoreGlobalFunctions();

// Later, retrieve in test
$ignoreList = test()->arch()->ignore; // Contains configured ignores
```

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

### Throwing an ArchExpectationFailedException

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/10-errors-and-objects.md

Example of creating a violation object and throwing the exception.

```php
$violation = new Violation('src/Models/User.php', 42, 45);
throw new ArchExpectationFailedException(
    $violation,
    "Class User violates architecture rule: uses forbidden dependency"
);
```

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

### Architecture Test Failure Message Example

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/14-quick-reference.md

Shows the structure of a failure message when an architecture expectation is not met.

```text
Expecting 'App\Services\UserService' only to use 'App\Repositories, App\Contracts'.
However, it also uses 'App\Http\Requests'.

File: src/Services/UserService.php
Line: 24
```

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

### Architecture test with filter methods

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/02-expectation-interface.md

Example of using filter methods like interfaces() combined with ignoringGlobalFunctions().

```php
expect('App')
    ->interfaces()
    ->toBeUsedIn('App')
    ->ignoringGlobalFunctions();
```

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

### Configure Hexagonal Architecture Constraints

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Enforces domain purity and strict dependency flow in a hexagonal architecture setup.

```php
beforeEach(function () {
    test()->arch()
        ->ignore('Exceptions')
        ->ignoreGlobalFunctions();
});

// Domain is pure and isolated
arch('domain purity')
    ->expect('App\Domain')
    ->classes()
    ->toUseNothing();

// Application layer uses domain
arch('application layer')
    ->expect('App\Application')
    ->toUse('App\Domain')
    ->ignoring('Dto');

// Infrastructure uses both
arch('infrastructure')
    ->expect('App\Infrastructure')
    ->toUse(['App\Domain', 'App\Application']);

// No circular dependencies
arch('no circular deps')
    ->expect('App\Domain')
    ->not()
    ->toUse(['App\Application', 'App\Infrastructure']);
```

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

### Handling dependencies input

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/07-collections-and-factories.md

Shows how to initialize Dependencies from single strings or arrays and pass them directly to a Blueprint.

```php
// Single dependency becomes array
$deps1 = Dependencies::fromExpectationInput('App\Contracts');
echo $deps1; // "App\Contracts"

// Multiple dependencies
$deps2 = Dependencies::fromExpectationInput([
    'App\Contracts',
    'App\Repositories',
    'Illuminate\Support',
]);
echo $deps2; // "App\Contracts, App\Repositories, Illuminate\Support"

// Can be passed directly to Blueprint
$blueprint = Blueprint::make(
    $targets,
    Dependencies::fromExpectationInput('App\Database')
);
```

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

### Get UserDefinedFunctions

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/12-complete-api-reference.md

Retrieves all user-defined functions.

```php
class Pest\Arch\Support\UserDefinedFunctions {
    public static function get(): array
}
```

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

### Complete factory workflow

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/07-collections-and-factories.md

Demonstrates the full lifecycle of creating dependencies, initializing a LayerFactory, and constructing a Blueprint.

```php
use Pest\Arch\Collections\Dependencies;
use Pest\Arch\Factories\LayerFactory;
use Pest\Arch\Repositories\ObjectsRepository;
use Pest\Arch\Options\LayerOptions;
use Pest\Arch\ValueObjects\Dependency;

// Create dependencies
$dependencies = Dependencies::fromExpectationInput([
    'App\Repositories',
    'App\Database',
]);

// Create factory
$repository = ObjectsRepository::getInstance();
$factory = new LayerFactory($repository);

// Create layers
$serviceOptions = new LayerOptions(
    exclude: ['App\Services\Internal'],
    excludeCallbacks: []
);

$serviceLayer = $factory->make($serviceOptions, 'App\Services');

// Use with Blueprint
$blueprint = Blueprint::make(
    Targets::fromExpectation(expect('App\Services')),
    $dependencies
);
```

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

### Instantiate Value Objects for architectural analysis

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/06-value-objects.md

Demonstrates creating Targets, Dependencies, and a Blueprint for architectural expectations, along with a Violation object for reporting.

```php
use Pest\Arch\ValueObjects\Targets;
use Pest\Arch\ValueObjects\Dependency;
use Pest\Arch\ValueObjects\Violation;
use Pest\Arch\Collections\Dependencies;
use Pest\Arch\Blueprint;

// Create targets from expectation
$targets = Targets::fromExpectation(expect('App\Services'));
// $targets->value === ['App\Services']

// Create dependencies
$dep1 = Dependency::fromString('App\Repositories');
$dep2 = Dependency::fromString('App\Contracts');
$dependencies = new Dependencies([$dep1, $dep2]);

// Create blueprint
$blueprint = Blueprint::make($targets, $dependencies);

// Create violation for error reporting
$violation = new Violation('src/Services/UserService.php', 42, 45);
```

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

### Complete architecture workflow

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/02-expectation-interface.md

Demonstrates chaining multiple architecture expectations and ignore rules.

```php
arch('service layer isolation')
    ->expect('App\Services')
    ->classes
    ->toBeFinal()
    ->toOnlyUse([
        'App\Repositories',
        'App\Contracts\Services',
        'Illuminate\Support',
    ])
    ->ignoring(['App\Services\BaseService', 'App\Services\Concerns'])
    ->and('App\Services')
    ->not
    ->toUse(['App\Controllers', 'App\Http\Requests']);
```

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

### Create and filter a layer

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/04-layer-class.md

Demonstrates initializing a layer from object descriptions and applying namespace-based filters.

```php
use Pest\Arch\Layer;
use PHPUnit\Architecture\Elements\ObjectDescription;

// Create layer from objects
$layer = Layer::fromBase([
    ObjectDescription::make('src/Controllers/UserController.php'),
    ObjectDescription::make('src/Controllers/AdminController.php'),
    ObjectDescription::make('src/Services/UserService.php'),
]);

// Filter by namespace
$controllers = $layer->leaveByNameStart('App\Controllers');

// Exclude internal classes
$publicControllers = $controllers->excludeByNameStart('App\Controllers\Internal');

// Iterate results
foreach ($publicControllers as $controller) {
    echo $controller->name . PHP_EOL;
}
```

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

### Execute complete configuration workflow

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/08-options-and-repositories.md

Combine test case options, expectation-based layer options, and repository-backed layer creation into a single workflow.

```php
use Pest\Arch\Options\TestCaseOptions;
use Pest\Arch\Options\LayerOptions;
use Pest\Arch\Repositories\ObjectsRepository;
use Pest\Arch\Factories\LayerFactory;

// Test case configuration
$testOptions = new TestCaseOptions();
test()->arch()->ignore = $testOptions
    ->ignore('App\Enums')
    ->ignore('App\Traits')
    ->ignoreGlobalFunctions()
    ->ignore;

// Per-expectation configuration
$expectation = expect('App\Models')
    ->toOnlyUse(['Illuminate\Database'])
    ->ignoring(['App\Models\Casts', 'App\Models\Factories']);

// Layer configuration
$layerOptions = LayerOptions::fromExpectation($expectation);

// Create layers
$repo = ObjectsRepository::getInstance();
$factory = new LayerFactory($repo);
$layer = $factory->make($layerOptions, 'App\Models');
```

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

### Create a Blueprint instance

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/03-blueprint-class.md

Use the make factory method to initialize a Blueprint with specific target and dependency layers.

```php
$blueprint = Blueprint::make(
    Targets::fromExpectation($expectation),
    Dependencies::fromExpectationInput($dependencies)
);
```

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

### Create ObjectDescription instances with ObjectDescriptionFactory

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/07-collections-and-factories.md

Demonstrates creating object descriptions from user and vendor files, including usage of the filtering parameter.

```php
// Create from user code file
$obj = ObjectDescriptionFactory::make('src/Models/User.php');
if ($obj) {
    echo $obj->name; // App\Models\User
}

// Create from vendor file
$obj = ObjectDescriptionFactory::make(
    'vendor/laravel/framework/src/Support/Facades/DB.php'
);

// With filtering
$obj = ObjectDescriptionFactory::make(
    'src/Services/UserService.php',
    true // only user-defined uses
);
```

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

### Layer creation with filtering

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/07-collections-and-factories.md

Illustrates how to configure LayerOptions to include or exclude specific namespaces and apply custom callback filters.

```php
$factory = new LayerFactory($repository);

// Create layer without exclusions
$fullLayer = $factory->make(
    new LayerOptions([], []),
    'App\Models'
);

// Create layer with namespace exclusion
$filtered = $factory->make(
    new LayerOptions(['App\Models\Internal'], []),
    'App\Models'
);

// Create layer with callback filtering
$filtered = $factory->make(
    new LayerOptions([], [
        fn($obj) => !$obj->reflectionClass->isAbstract()
    ]),
    'App\Models'
);
```

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

### PhpCoreExpressions::getClass()

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/09-support-utilities.md

Performs a reverse lookup to get the PhpParser class for a given language construct name.

```APIDOC
## PhpCoreExpressions::getClass()

### Description
Gets the PhpParser class for a language construct name like 'clone' or 'empty'.

### Signature
`public static function getClass(string $name): ?class-string<Expr>`

### Parameters
- **$name** (string) - Required - Expression name like 'clone', 'empty', etc.

### Returns
- **class-string<Expr>|null** - Expression class or null if not found

### Example
```php
$class = PhpCoreExpressions::getClass('empty');
// Returns Empty_::class
```
```

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

### Apply configuration correctly

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Ensure configuration is applied in beforeEach to avoid late execution during test runs.

```php
// Ensure configuration is in beforeEach, not inside test
beforeEach(function () {  // ✓ Correct
    test()->arch()->ignore('Legacy');
});

test('...', function () {
    test()->arch()->ignore('Legacy');  // ✗ Too late - test already running
});
```

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

### Run project tests

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/CONTRIBUTING.md

Execute the test suite to verify changes.

```bash
composer test
```

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

### Using Pest Architecture Expectations

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/05-expectation-classes.md

Demonstrates the standard usage of architecture expectations via the fluent API, noting that internal classes are handled by the framework.

```php
// These internal classes are used by the Pest framework
// You don't typically instantiate them directly

// Instead, you use them through Pest's expectation syntax:
expect('App\Models')
    ->toOnlyUse(['Illuminate\Database\Eloquent\Model'])
    ->ignoring('App\Models\Concerns');

// The framework internally does something like:
// $expectation = expect('App\Models');
// ToOnlyUse::make($expectation, ['Illuminate\Database\Eloquent\Model'])
//   ->ignoring('App\Models\Concerns');
```

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

### Create Dependencies from Input

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/07-collections-and-factories.md

Use fromExpectationInput to instantiate a Dependencies collection from either a single string or an array of strings.

```php
// Single string
$deps1 = Dependencies::fromExpectationInput('App\Repositories');
// Creates Dependencies with one Dependency object

// Array of strings
$deps2 = Dependencies::fromExpectationInput([
    'App\Repositories',
    'App\Services',
    'Illuminate\Support',
]);
// Creates Dependencies with three Dependency objects
```

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

### Define and validate architectural expectations with Blueprint

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/03-blueprint-class.md

Use the Blueprint class to define target layers and their dependencies, then execute validation using expectToUse.

```php
$targets = Targets::fromExpectation(expect('App\Services'));
$dependencies = Dependencies::fromExpectationInput(['App\Repositories']);
$blueprint = Blueprint::make($targets, $dependencies);

$options = LayerOptions::fromExpectation($expectation);

$blueprint->expectToUse(
    $options,
    fn(string $target, string $dep) =>
        throw new ExpectationFailedException("$target must use $dep")
);
```

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

### Method Chaining in Architecture Expectations

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/14-quick-reference.md

Demonstrates how to chain multiple architecture expectations together for fluent testing.

```php
expect('App\Models')
    ->classes()
    ->toBeFinal()
    ->toOnlyUse(['Database'])
    ->ignoring('Concerns')
    ->and('App\Repositories')
    ->not()
    ->toUse('App\Http');
```

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

### Create a Layer instance

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/04-layer-class.md

Use the fromBase factory method to initialize a Layer from an array of ObjectDescription instances.

```php
$objects = [
    ObjectDescription::make('src/Services/UserService.php'),
    ObjectDescription::make('src/Services/ProductService.php'),
];
$layer = Layer::fromBase($objects);
```

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

### Targets fromExpectation Usage

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/06-value-objects.md

Demonstrates creating Targets instances from single strings or arrays of strings via Pest expectations.

```php
$targets = Targets::fromExpectation(expect('App\Models'));
// $targets->value === ['App\Models']

$targets = Targets::fromExpectation(expect(['App\Controllers', 'App\Services']));
// $targets->value === ['App\Controllers', 'App\Services']
```

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

### make()

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/07-collections-and-factories.md

Creates a Layer instance from a namespace pattern with optional filtering.

```APIDOC
## make(LayerOptions $options, string $name, bool $onlyUserDefinedUses = true)

### Description
Creates a Layer instance from a namespace pattern. The $name parameter supports exact namespaces or wildcard patterns (e.g., 'App\Controllers\*').

### Parameters
- **$options** (LayerOptions) - Required - Configuration including exclusions and callbacks.
- **$name** (string) - Required - Namespace pattern.
- **$onlyUserDefinedUses** (bool) - Optional - Default: true. If true, only user-defined uses are included.

### Return Type
Pest\Arch\Layer

### Example
```php
$factory = new LayerFactory($repository);

// Simple namespace
$layer = $factory->make($options, 'App\Services');

// Wildcard pattern
$layer = $factory->make($options, 'App\Controllers\*');
```
```

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

### Configure PHP Settings for Architecture Analysis

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Recommended php.ini settings to handle memory-intensive analysis and ensure proper error reporting.

```ini
; Memory limit - architecture analysis can be memory-intensive
memory_limit = 512M

; Error reporting - ensure all errors are caught
error_reporting = E_ALL
display_errors = 1

; Execution time - large codebases may need more time
max_execution_time = 60
```

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

### Plugin Argument Handling

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/11-plugin-and-architectable.md

Manual demonstration of how the plugin transforms CLI arguments into Pest group filters.

```php
use Pest\Arch\Plugin;

// Plugin is typically instantiated by Pest framework
$plugin = new Plugin();

// Handle --arch flag
$args = ['--arch'];
$result = $plugin->handleArguments($args);
// Result: ['--group=arch']

// Handle --exclude-arch flag
$args = ['--exclude-arch'];
$result = $plugin->handleArguments($args);
// Result: ['--exclude-group=arch']

// Pass through other arguments
$args = ['--filter=test', '--verbose'];
$result = $plugin->handleArguments($args);
// Result: ['--filter=test', '--verbose'] (unchanged)
```

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

### Configure Test Case Options

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/12-complete-api-reference.md

Handles configuration settings at the individual test case level.

```php
class Pest\Arch\Options\TestCaseOptions {
    public array $ignore;
    public function ignore(array|string $targetsOrDependencies): self
    public function ignoreGlobalFunctions(): self
}
```

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

### Create a Dependency instance

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/06-value-objects.md

Use the fromString factory method to instantiate a Dependency. It validates that the provided string does not contain forward slashes.

```php
$dependency = Dependency::fromString('App\Repositories');
// $dependency->value === 'App\Repositories'
```

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

### ObjectDescriptionFactory::make()

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/07-collections-and-factories.md

Creates an ObjectDescription instance from a given file path, with options to filter for user-defined uses.

```APIDOC
## ObjectDescriptionFactory::make()

### Description
Creates an ObjectDescription from a file path. This method handles vendor files differently and allows filtering to only include user-defined class uses.

### Signature
`public static function make(string $filename, bool $onlyUserDefinedUses = true): ?PHPUnit\Architecture\Elements\ObjectDescription`

### Parameters
- **$filename** (string) - Required - Full or relative path to a PHP file.
- **$onlyUserDefinedUses** (bool) - Optional (Default: true) - Filter to only user-defined class uses.

### Return Type
`PHPUnit\Architecture\Elements\ObjectDescription|null` - Returns the object description or null if creation fails.

### Example
```php
// Create from user code file
$obj = ObjectDescriptionFactory::make('src/Models/User.php');

// With filtering
$obj = ObjectDescriptionFactory::make('src/Services/UserService.php', true);
```
```

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

### Run unit tests

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/CONTRIBUTING.md

Execute only the unit test suite.

```bash
composer test:unit
```

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

### Configure Layer Options

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/12-complete-api-reference.md

Handles configuration settings for a specific layer during architectural testing.

```php
class Pest\Arch\Options\LayerOptions {
    public readonly array $exclude;
    public readonly array $excludeCallbacks;
    public static function fromExpectation(SingleArchExpectation $expectation): self
}
```

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

### LayerFactory make() Method Signature

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/07-collections-and-factories.md

Signature for the make method used to create a Layer instance.

```php
public function make(
    Pest\Arch\Options\LayerOptions $options,
    string $name,
    bool $onlyUserDefinedUses = true
): Pest\Arch\Layer
```

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

### Migrate from PHPUnit architecture tests

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Compare the legacy PHPUnit class-based approach with the cleaner Pest Plugin Arch syntax.

```php
// Before (PHPUnit architecture)
use PHPUnit\Architecture\ArchitectureAsserts;

class ArchitectureTest extends TestCase {
    use ArchitectureAsserts;
    
    public function test_models_are_final() {
        $this->assertDependsOn(...);
    }
}

// After (Pest Plugin Arch)
arch('models are final')
    ->expect('App\Models')
    ->classes
    ->toBeFinal();
```

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

### Blueprint::make()

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/03-blueprint-class.md

Factory method to create a new Blueprint instance for architecture testing.

```APIDOC
## static Blueprint::make(Targets $target, Dependencies $dependencies)

### Description
Creates and returns a new Blueprint instance with the given target and dependency layers.

### Parameters
- **$target** (Targets) - Required - The target layer(s) to test
- **$dependencies** (Dependencies) - Required - The dependency layer(s) allowed or restricted

### Return Type
- **self** - A new Blueprint instance
```

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

### arch()

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/12-complete-api-reference.md

The primary entry point for defining architecture tests. It allows you to expect specific namespaces or classes and apply architectural rules.

```APIDOC
## arch(string $description)

### Description
Defines a new architecture test with a given description. This function returns an expectation object that can be chained with architectural constraints.

### Usage
```php
arch('models are final')
    ->expect('App\Models')
    ->classes
    ->toBeFinal();
```
```

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

### Manage memory limits

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Increase memory allocation for architecture tests via CLI or php.ini.

```bash
# Increase memory limit
php -d memory_limit=1G vendor/bin/pest --arch

# Or configure in php.ini
memory_limit = 1024M
```

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

### Declare architecture rules with expectations

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/INDEX.md

Use the fluent API to define allowed dependencies for a specific namespace while optionally ignoring certain classes.

```php
expect('Target\Namespace')
    ->toOnlyUse(['Allowed\Dependency'])
    ->ignoring('Exception\Class');
```

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

### Configure Test Case Level Options

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Use the arch() method within a test file to define global ignores for all architecture tests in that file.

```php
<?php

use Pest\Arch\Options\TestCaseOptions;

beforeEach(function () {
    // Get the test case options
    $options = test()->arch();
    
    // Add ignores
    $options->ignore('App\Models\Concerns');
    $options->ignore(['App\Models\Casts', 'App\Models\Factories']);
    
    // Ignore all global functions
    $options->ignoreGlobalFunctions();
});

// All architecture tests in this file inherit the above configuration
arch('models behavior')
    ->expect('App\Models')
    ->toOnlyUse(['Database']);
```

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

### Lint the codebase

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/CONTRIBUTING.md

Execute the linter to ensure code style compliance.

```bash
composer lint
```

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

### Blueprint::expectToUse()

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/03-blueprint-class.md

Verifies that a target layer uses the specified dependencies.

```APIDOC
## Blueprint::expectToUse(LayerOptions $options, callable $failure)

### Description
Tests that the target layer uses at least one of the specified dependencies. If no dependency is found, the failure callback is invoked.

### Parameters
- **$options** (LayerOptions) - Required - Configuration for layer filtering and exclusions
- **$failure** (callable(string, string): mixed) - Required - Callback invoked if expectation fails

### Return Type
- **void**
```

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

### Discover project namespaces and autoloader with Composer utility

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/09-support-utilities.md

Use the Composer utility to retrieve user-defined namespaces, directory mappings, and the underlying autoloader instance.

```php
use Pest\Arch\Support\Composer;

// Discover project namespaces
$namespaces = Composer::userNamespaces();
echo implode(', ', $namespaces);
// Outputs: "App, Database, Modules"

// Get directory mapping
$map = Composer::userNamespacesWithDirectories();
foreach ($map as $dir => $namespace) {
    echo "$namespace => $dir\n";
}

// Access autoloader directly
$loader = Composer::loader();
$prefixes = $loader->getPrefixesPsr4();
```

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

### Project Directory Structure

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/INDEX.md

The file hierarchy for the pest-plugin-arch source code, illustrating the separation of concerns between expectations, factories, and core engine logic.

```text
src/
├── Autoload.php                          # Bootstrap, arch() function
├── Blueprint.php                         # Core testing engine
├── GroupArchExpectation.php             # Aggregated expectations
├── Layer.php                            # Layer wrapper
├── PendingArchExpectation.php           # Filter container
├── Plugin.php                           # Pest plugin integration
├── SingleArchExpectation.php            # Single expectation
├── Collections/
│   └── Dependencies.php                 # Dependency collection
├── Concerns/
│   └── Architectable.php               # Trait for test cases
├── Contracts/
│   └── ArchExpectation.php             # Interface
├── Exceptions/
│   └── ArchExpectationFailedException.php # Custom exception
├── Expectations/
│   ├── Targeted.php                    # Custom assertions
│   ├── ToBeUsedIn.php
│   ├── ToBeUsedInNothing.php
│   ├── ToOnlyBeUsedIn.php
│   ├── ToOnlyUse.php
│   ├── ToUse.php
│   └── ToUseNothing.php
├── Factories/
│   ├── LayerFactory.php                # Create layers
│   └── ObjectDescriptionFactory.php    # Create objects
├── Objects/
│   ├── FunctionDescription.php
│   ├── ObjectDescription.php
│   ├── ObjectDescriptionBase.php
│   └── VendorObjectDescription.php
├── Options/
│   ├── LayerOptions.php               # Layer config
│   └── TestCaseOptions.php            # Test case config
├── Repositories/
│   └── ObjectsRepository.php          # Object cache
├── Support/
│   ├── AssertLocker.php
│   ├── Composer.php
│   ├── FileLineFinder.php
│   ├── PhpCoreExpressions.php
│   ├── ReflectionClassForFunction.php
│   └── UserDefinedFunctions.php
└── ValueObjects/
    ├── Dependency.php
    ├── Targets.php
    └── Violation.php
```

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

### Dependencies::__toString

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/07-collections-and-factories.md

Converts the collection of dependencies into a single comma-separated string.

```APIDOC
## __toString()

### Description
Joins all dependency values with a comma-space separator. This is useful for error messages and logging.

### Return Type
- **string** - The comma-separated string representation of the dependencies.
```

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

### Implement Plugin Interface

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/12-complete-api-reference.md

Defines the structure for integrating custom plugins with the Pest CLI.

```php
class Pest\Arch\Plugin implements HandlesArguments {
    public function handleArguments(array $arguments): array
}
```

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

### Configure Custom Expectations

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Programmatically define test case and layer options for architecture expectations.

```php
use Pest\Arch\Options\TestCaseOptions;
use Pest\Arch\Options\LayerOptions;

// Test case level
$testOptions = new TestCaseOptions();
$testOptions->ignore(['Internal', 'Legacy']);
test()->arch()->ignore = $testOptions->ignore;

// Layer level
$layerOptions = LayerOptions::fromExpectation(
    expect('App\Services')
        ->toOnlyUse(['Database'])
        ->ignoring('Old\Implementation')
);

// Use in blueprint
$blueprint = Blueprint::make($targets, $dependencies);
$blueprint->expectToOnlyUse($layerOptions, $failureCallback);
```

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

### Convert Dependencies to String

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/07-collections-and-factories.md

The __toString method joins dependency values into a comma-separated string, suitable for logging or error reporting.

```php
$deps = Dependencies::fromExpectationInput(['App\Repo', 'App\Services']);
echo $deps; // Outputs: "App\Repo, App\Services"
```

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

### Handle array inputs in Targets

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/06-value-objects.md

Shows how Targets::fromExpectation normalizes single strings into arrays while preserving existing array structures.

```php
// Single target string becomes array
$targets1 = Targets::fromExpectation(expect('App\Models'));
// Result: Targets with $value = ['App\Models']

// Array targets stay as array
$targets2 = Targets::fromExpectation(
    expect(['App\Models', 'App\Controllers'])
);
// Result: Targets with $value = ['App\Models', 'App\Controllers']
```

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

### Composer::allNamespacesWithDirectories()

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/09-support-utilities.md

Maps all non-vendor namespaces to their directories, including test namespaces.

```APIDOC
## Composer::allNamespacesWithDirectories()

### Description
Returns a mapping of directory paths to namespace names for all non-vendor code, including test namespaces.

### Signature
`public static function allNamespacesWithDirectories(): array<string, string>`

### Returns
- **array<string, string>** - Map of directory to namespace
```

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

### Define ArchExpectation interface

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/02-expectation-interface.md

The base interface for architecture testing expectations.

```php
interface Pest\Arch\Contracts\ArchExpectation extends Pest\Expectation
```

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

### CLI argument transformation for architecture tests

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/11-plugin-and-architectable.md

Demonstrates how the plugin converts the --arch flag into a group filter for test execution.

```bash
# Original command
pest --arch --filter=models --verbose

# After Plugin::handleArguments()
pest --group=arch --filter=models --verbose
```

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

### Define TestCaseOptions Configuration

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/13-types-reference.md

Configuration class for test case level settings, including ignore methods.

```php
class Pest\Arch\Options\TestCaseOptions {
    public array $ignore;  // array<int, string>
}
```

```php
public function ignore(array|string $targetsOrDependencies): self
public function ignoreGlobalFunctions(): self
```

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

### Retrieve ObjectsRepository Instance

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/08-options-and-repositories.md

Access the singleton instance of the repository.

```php
$repository = ObjectsRepository::getInstance();
```

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

### Assert Dependency Usage Targets

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/12-complete-api-reference.md

Methods to verify where specific dependencies are used.

```php
expect('App\Contracts\Repository')->toBeUsedIn('App\Services');
```

```php
expect('App\Database')->toOnlyBeUsedIn(['App\Repositories']);
```

```php
expect('App\Internal\Config')->toBeUsedInNothing();
```

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

### Map user namespaces to directories with Composer::userNamespacesWithDirectories

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/09-support-utilities.md

Returns a mapping of absolute directory paths to namespace names for user code.

```php
$map = Composer::userNamespacesWithDirectories();
// [
//     '/project/src' => 'App',
//     '/project/database' => 'Database',
// ]
```

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

### Retrieve Objects by Namespace

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/08-options-and-repositories.md

Fetch object descriptions for a specific namespace, class, or function, with options to filter user-defined uses.

```php
$repository = ObjectsRepository::getInstance();

// Get all models
$models = $repository->allByNamespace('App\Models');

// Get single class as array
$user = $repository->allByNamespace('App\Models\User');

// Get all including vendor uses
$all = $repository->allByNamespace('App\Services', false);
```

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

### Pre-commit Hook Implementation

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

A shell script to run architecture tests before committing code, aborting the commit if tests fail.

```bash
#!/bin/bash
# .git/hooks/pre-commit

vendor/bin/pest --arch
if [ $? -ne 0 ]; then
    echo "Architecture tests failed. Commit aborted."
    exit 1
fi
```

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

### Create Custom Layers

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Instantiate layers with specific exclusion rules using the LayerFactory.

```php
use Pest\Arch\Factories\LayerFactory;
use Pest\Arch\Repositories\ObjectsRepository;
use Pest\Arch\Options\LayerOptions;

$repository = ObjectsRepository::getInstance();
$factory = new LayerFactory($repository);

// Create layer with specific excludes
$options = new LayerOptions(
    exclude: ['App\Models\Internal', 'App\Models\Deprecated'],
    excludeCallbacks: []
);

$layer = $factory->make($options, 'App\Models');
```

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

### Retrieve objects with ObjectsRepository

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/08-options-and-repositories.md

Access the singleton ObjectsRepository to query classes by namespace and generate layers via LayerFactory.

```php
use Pest\Arch\Repositories\ObjectsRepository;
use Pest\Arch\Factories\LayerFactory;
use Pest\Arch\Options\LayerOptions;

// Get singleton
$repository = ObjectsRepository::getInstance();

// Retrieve objects
$serviceObjects = $repository->allByNamespace('App\Services');
$modelObjects = $repository->allByNamespace('App\Models');

// Use with LayerFactory
$factory = new LayerFactory($repository);
$serviceLayer = $factory->make(
    new LayerOptions([], []),
    'App\Services'
);

// Get single class
$user = $repository->allByNamespace('App\Models\User');
```

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

### Configure ignore list with ignoring

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/05-expectation-classes.md

Adds specific targets or dependencies to the ignore list for the current expectation.

```php
public function ignoring(array<int, string>|string $targetsOrDependencies): self
```

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

### Manage LayerOptions from expectations

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/08-options-and-repositories.md

Extract layer options from an existing expectation to apply them within a custom Blueprint test.

```php
use Pest\Arch\Options\LayerOptions;

// From an expectation with ignores
$expectation = expect('App\Services')
    ->toOnlyUse(['App\Repositories', 'App\Database'])
    ->ignoring('App\Services\Internal');

$options = LayerOptions::fromExpectation($expectation);

// Use with Blueprint for testing
$blueprint->expectToOnlyUse(
    $options,
    fn(string $target, string $allowed, string $disallowed, ?Violation $v) =>
        throw new Exception("Violation found")
);
```

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

### Configure Per-Expectation Settings

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Apply specific ignore rules to individual expectations within an architecture test chain.

```php
arch('models dependencies')
    ->expect('App\Models')
    ->toOnlyUse(['Illuminate\Database\Eloquent\Model'])
    ->ignoring('App\Models\Casts')
    ->and('App\Repositories')
    ->toUse('App\Models')
    ->ignoring('App\Repositories\Cache');
```

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

### Map all non-vendor namespaces with Composer::allNamespacesWithDirectories

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/09-support-utilities.md

Provides a mapping of directory paths to namespaces, including test namespaces but excluding vendor directories.

```php
$map = Composer::allNamespacesWithDirectories();
// Same as userNamespacesWithDirectories() but includes Tests\ namespace
```

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

### Manage helper functions with UserDefinedFunctions

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/09-support-utilities.md

Retrieve all user-defined helper functions and integrate them with test options to exclude them from architecture tests.

```php
use Pest\Arch\Support\UserDefinedFunctions;
use Pest\Arch\Options\TestCaseOptions;

// Get all helper functions
$helpers = UserDefinedFunctions::get();

// Use with test options
$options = new TestCaseOptions();
$options->ignore(UserDefinedFunctions::get());
// Now all helpers are excluded from architecture tests
```

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

### Modular Architecture Pattern

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/INDEX.md

Visual representation of modular isolation via namespaces.

```text
User Module ← Posts Module ← Comments Module
(isolated by namespace)
```

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

### Targets Constructor

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/06-value-objects.md

The constructor accepts an array of strings representing target class names or namespace prefixes.

```php
public function __construct(public readonly array $value)
```

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

### Run Test Suites via CLI

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Execute specific test suites using the pest command line interface.

```bash
pest --testsuite=architecture
pest --testsuite=unit
pest --testsuite=architecture,unit
```

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

### Basic architecture test with namespace

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/01-arch-function.md

Verify that classes within a specific namespace only depend on allowed namespaces.

```php
arch('repositories only use services')
    ->expect('App\Repositories')
    ->toOnlyUse(['App\Services']);
```

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

### Layer::getBase

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/04-layer-class.md

Returns the underlying base layer instance.

```APIDOC
## Layer::getBase()

### Description
Provides access to the underlying `PHPUnit\Architecture\Elements\Layer\Layer` instance if direct access to the base layer is needed.

### Return Type
- **PHPUnit\Architecture\Elements\Layer\Layer** - The wrapped base layer
```

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

### Debugging Architecture Violations

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/14-quick-reference.md

Use toUseNothing() to force a failure and list all current dependencies for debugging.

```php
// Create temporary test to debug
arch('debug - list all models')
    ->expect('App\Models')
    ->toUseNothing(); // Will fail and show all uses
```

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

### Catching and handling architecture exceptions

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/10-errors-and-objects.md

Use try-catch blocks to handle ArchExpectationFailedException and standard PHPUnit ExpectationFailedException when running architecture tests.

```php
use PHPUnit\Framework\ExpectationFailedException;
use Pest\Arch\Exceptions\ArchExpectationFailedException;

test('architecture expectations', function () {
    try {
        expect('App\Models')
            ->toOnlyUse(['Illuminate\Database'])
            ->ignoring(['App\Models\Casts']);
    } catch (ArchExpectationFailedException $e) {
        // Architecture error with precise location
        $this->fail($e->getMessage());
    } catch (ExpectationFailedException $e) {
        // Other Pest expectation error
        $this->fail($e->getMessage());
    }
});
```

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

### Define LayerOptions Configuration

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/13-types-reference.md

Configuration class for layer processing, including exclusion lists.

```php
class Pest\Arch\Options\LayerOptions {
    public readonly array $exclude;           // array<int, string>
    public readonly array $excludeCallbacks;  // array<int, callable>
}
```

```php
public static function fromExpectation(SingleArchExpectation $expectation): self
```

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

### Dependency Assertions

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/14-quick-reference.md

Verify usage patterns and dependencies between namespaces or classes.

```php
// Target uses dependency
expect('App\Services')->toUse('App\Repositories');

// Target uses only specific dependencies
expect('App\Models')->toOnlyUse(['Illuminate\Database\Eloquent\Model']);

// Target uses nothing
expect('App\ValueObjects')->toUseNothing();

// Dependency is used by targets
expect('App\Contracts\Repository')->toBeUsedIn('App\Services');

// Dependency is used only by targets
expect('App\Database')->toOnlyBeUsedIn(['App\Repositories']);

// Dependency is not used anywhere
expect('App\Internal\Config')->toBeUsedInNothing();
```

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

### Execute Architecture Tests in Parallel

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Run tests across multiple processes to improve performance on large codebases.

```bash
# Run tests in parallel
pest --arch --parallel

# Specify number of processes
pest --arch --parallel --processes=4
```

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

### Test Architecture Conventions

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/14-quick-reference.md

Verifies architectural standards using standard Pest test syntax.

```php
// This test verifies the architecture is correct
test('models follow conventions', function () {
    expect('App\Models')->classes->toBeFinal();
});
```

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

### Configure composer.json

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

The plugin is registered in the extra section of the composer.json file to enable automatic loading.

```json
{
    "name": "pestphp/pest-plugin-arch",
    "require": {
        "php": "^8.4",
        "pestphp/pest-plugin": "^5.0.0",
        "ta-tikoma/phpunit-architecture-test": "^0.8.7"
    },
    "extra": {
        "pest": {
            "plugins": [
                "Pest\\Arch\\Plugin"
            ]
        }
    }
}
```

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

### Manage Dependency Collections

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/12-complete-api-reference.md

A collection of dependencies that implements Stringable.

```php
class Pest\Arch\Collections\Dependencies implements Stringable {
    public readonly array $values;
    public static function fromExpectationInput(array|string $values): self
    public function __toString(): string
}
```

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

### Run type checks

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/CONTRIBUTING.md

Execute static analysis to verify type safety.

```bash
composer test:types
```

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

### Run architecture tests via CLI

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/14-quick-reference.md

Execute architecture tests using the Pest CLI with various flags.

```bash
# Run only architecture tests
pest --arch

# Run all except architecture tests
pest --exclude-arch

# Run architecture tests matching pattern
pest --arch --filter=models

# Run with verbose output
pest --arch --verbose

# Run in parallel
pest --arch --parallel
```

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

### Assert Dependency Usage

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/12-complete-api-reference.md

Methods to verify which layers or dependencies are used by the target.

```php
expect('App\Services')->toUse('App\Repositories');
expect(['App\Controllers', 'App\Services'])->toUse(['App\Database']);
```

```php
expect('App\Models')->toOnlyUse(['Illuminate\Database\Eloquent\Model']);
```

```php
expect('App\ValueObjects')->toUseNothing();
```

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

### Debugging Class Dependencies

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/14-quick-reference.md

Use these patterns to inspect what a class uses or what uses a specific class by forcing a test failure.

```php
// This will show what App\Models actually uses
arch('debug models uses')
    ->expect('App\Models')
    ->toUse(['anything']); // Will fail and show dependencies
```

```php
// This will show what uses App\Database
arch('debug database usage')
    ->expect('App\Database')
    ->toBeUsedIn(['anything']); // Will fail and show users
```

```php
// Verify class filters work
arch('debug classes')
    ->expect('App')
    ->classes()
    ->toUseNothing(); // Will show only classes
```

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

### Verify target layer usage

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/03-blueprint-class.md

Use expectToUse to ensure a target layer utilizes at least one of the provided dependencies, triggering a failure callback if not.

```php
$blueprint->expectToUse(
    $options,
    fn(string $target, string $dependency) =>
        throw new ExpectationFailedException(
            "Target '$target' does not use '$dependency'"
        )
);
```

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

### Instantiate and use a Violation

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/06-value-objects.md

Create a Violation instance to identify a specific file and line range for an architecture rule failure. Typically passed to an ArchExpectationFailedException.

```php
$violation = new Violation('src/Models/User.php', 15, 15);

throw new ArchExpectationFailedException(
    $violation,
    "Class violates architecture rule"
);

// This will highlight line 15 in src/Models/User.php
```

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

### Configure test-level ignores

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/14-quick-reference.md

Define global ignores for specific namespaces or functions within a beforeEach block.

```php
beforeEach(function () {
    test()->arch()
        ->ignore('App\Models\Concerns')
        ->ignore(['App\Traits', 'App\Enums'])
        ->ignoreGlobalFunctions();
});
```

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

### Configure Test Suites in pest.xml

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Define architecture and unit test suites within the Pest configuration file.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
    <testsuite name="architecture">
        <directory suffix="Arch.php">tests</directory>
    </testsuite>
    <testsuite name="unit">
        <directory suffix="Test.php">tests</directory>
    </testsuite>
</testsuites>
```

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

### Composer::userNamespacesWithDirectories()

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/09-support-utilities.md

Maps user-defined namespaces to their corresponding absolute directory paths.

```APIDOC
## Composer::userNamespacesWithDirectories()

### Description
Returns a mapping of directory paths to namespace names for all user code. Keys are absolute paths, values are namespace names.

### Signature
`public static function userNamespacesWithDirectories(): array<string, string>`

### Returns
- **array<string, string>** - Map of directory to namespace
```

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

### Inspect Architecture Configuration

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Access the architecture test options object within a test to dump and inspect current ignore lists.

```php
test('debug configuration', function () {
    $options = test()->arch();
    
    dump('Ignore list:', $options->ignore);
    
    // Run test and examine output
    expect('App\Models')
        ->toUse('Database');
});
```

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

### Composer Utility

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/09-support-utilities.md

Provides methods to interact with the project's Composer configuration, including namespace discovery and autoloader access.

```APIDOC
## Composer::userNamespaces()

### Description
Retrieves the list of user-defined namespaces in the project.

### Returns
- **array** - A list of namespace strings.

## Composer::userNamespacesWithDirectories()

### Description
Retrieves a mapping of namespaces to their respective directories.

### Returns
- **array** - An associative array where keys are directories and values are namespaces.

## Composer::loader()

### Description
Accesses the underlying Composer autoloader instance.

### Returns
- **\Composer\Autoload\ClassLoader** - The autoloader instance.
```

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

### Registering the Pest Arch plugin in composer.json

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/11-plugin-and-architectable.md

Add the plugin class to the extra configuration section to enable it during the Pest bootstrap process.

```json
{
    "extra": {
        "pest": {
            "plugins": [
                "Pest\\Arch\\Plugin"
            ]
        }
    }
}
```

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

### Use Wildcard Patterns in Expectations

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/15-configuration-guide.md

Target specific sub-layers or entire namespaces using wildcard syntax.

```php
// Match one level deep
expect('App\Controllers\*')
    ->toUse('App\Services');

// This matches:
// - App\Controllers\UserController
// - App\Controllers\PostController
// But NOT:
// - App\Controllers\Admin\DashboardController

// Match entire tree
expect('App\**')
    ->toUse(['Database', 'Http']);

// This matches all classes under App namespace
```

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

### Architecture Test with Dependencies

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/12-complete-api-reference.md

Restricts the allowed dependencies for a specific namespace.

```php
arch('services use repositories')
    ->expect('App\Services')
    ->toOnlyUse(['App\Repositories', 'Illuminate\Support']);
```

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

### Blueprint Class Definition

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/12-complete-api-reference.md

Orchestrates architecture testing logic through static factory methods and expectation handlers.

```php
class Pest\Arch\Blueprint {
    public static function make(Targets $target, Dependencies $dependencies): self
    public function expectToUse(LayerOptions $options, callable $failure): void
    public function expectToOnlyUse(LayerOptions $options, callable $failure): void
    public function expectToOnlyBeUsedIn(LayerOptions $options, callable $failure): void
    public function targeted(callable $callback, LayerOptions $options, callable $failure, callable $lineFinder): void
}
```

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

### Layered Architecture Pattern

Source: https://github.com/pestphp/pest-plugin-arch/blob/5.x/_autodocs/INDEX.md

Visual representation of a standard layered dependency flow.

```text
Controllers → Services → Repositories → Models
```
Tokens:
Raw