PHPUnit Architecture Test

https://github.com/ta-tikoma/phpunit-architecture-test
Admin
PHPUnit Architecture Test is a tool that allows developers to write architecture tests alongside...
Tokens:4,364
Snippets:23
Trust Score:6.5
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install and Setup PHPUnit Architecture Test

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Instructions for installing the PHPUnit Architecture Test library via Composer and integrating its trait into a custom test base class.

```php
// Install via composer
// composer require --dev ta-tikoma/phpunit-architecture-test

// Add trait to your test base class
namespace Tests;

use PHPUnit\Framework\TestCase as BaseTestCase;
use PHPUnit\Architecture\ArchitectureAsserts;

abstract class TestCase extends BaseTestCase
{
    use ArchitectureAsserts;
}
```

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

### Install PHPUnit Architecture Test via Composer (Bash)

Source: https://github.com/ta-tikoma/phpunit-architecture-test/blob/main/README.md

This command installs the `ta-tikoma/phpunit-architecture-test` package as a development dependency using Composer. This is the standard method for adding the library to your PHP project.

```bash
composer require --dev ta-tikoma/phpunit-architecture-test
```

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

### Define Layers by Namespace - PHPUnit Architecture Test

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Example of defining architectural layers by filtering classes based on their namespace prefixes. It demonstrates asserting that controllers depend on services but not repositories.

```php
use Tests\TestCase;

class ArchitectureTest extends TestCase
{
    public function test_controllers_depend_on_services_not_repositories(): void
    {
        // Create layers by namespace prefix
        $controllers  = $this->layer()->leaveByNameStart('App\Controllers');
        $services     = $this->layer()->leaveByNameStart('App\Services');
        $repositories = $this->layer()->leaveByNameStart('App\Repositories');

        // Controllers must use services
        $this->assertDependOn($controllers, $services);

        // Controllers must not directly use repositories
        $this->assertDoesNotDependOn($controllers, $repositories);

        // Services must use repositories
        $this->assertDependOn($services, $repositories);
    }
}
```

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

### Test Method Return Types Against Layers

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Ensures that method return types align with defined architectural boundaries. This example verifies that repository methods return domain models and controller methods return Response objects.

```php
public function test_repositories_return_domain_models(): void
{
    $repositories = $this->layer()->leaveByNameStart('App\Repositories\');
    $models = $this->layer()->leaveByNameStart('App\Models\');

    // Repository methods must return domain models
    $this->assertOutgoingFrom($repositories, $models);
}

public function test_controllers_return_responses(): void
{
    $controllers = $this->layer()->leaveByNameStart('App\Controllers\');
    $responses = $this->layer()->leaveByNameStart('Symfony\Component\HttpFoundation\Response');

    // Controller methods should return Response objects
    $this->assertOutgoingFrom($controllers, $responses);
}
```

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

### Filter Layers by Path - PHPUnit Architecture Test

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Demonstrates filtering classes based on their filesystem location to define layers. This example enforces that application code does not depend on test code.

```php
public function test_app_code_does_not_depend_on_tests(): void
{
    // Get all application code from src/ directory
    $app = $this->layer()->leaveByPathStart('/src');

    // Get all test code from tests/ directory
    $tests = $this->layer()->leaveByPathStart('/tests');

    // Application code must not depend on test code
    $this->assertDoesNotDependOn($app, $tests);

    // Tests can depend on application code (expected)
    $this->assertDependOn($tests, $app);
}
```

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

### Filter Layers by Regex - PHPUnit Architecture Test

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Illustrates using regular expressions to define precise layer boundaries for complex architectural rules. This example ensures feature modules are isolated from each other.

```php
public function test_feature_modules_are_isolated(): void
{
    // Match classes in Feature\Billing namespace
    $billing = $this->layer()->leaveByNameRegex('/^App\\Feature\\Billing\\/');

    // Match classes in Feature\Reporting namespace
    $reporting = $this->layer()->leaveByNameRegex('/^App\\Feature\\Reporting\\/');

    // Feature modules should not depend on each other
    $this->assertDoesNotDependOn($billing, $reporting);
    $this->assertDoesNotDependOn($reporting, $billing);
}
```

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

### Test Method Argument Types Against Layers

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Validates that method arguments in specified classes originate from expected architectural layers. This example checks if service constructors correctly use repository arguments.

```php
public function test_service_constructors_use_repositories(): void
{
    // Get service classes
    $services = $this->layer()->leaveByNameStart('App\Services\');

    // Get repository interfaces
    $repositories = $this->layer()->leaveByNameStart('App\Repositories\');

    // Service constructors must have repository arguments
    $this->assertIncomingsFrom($services, $repositories, ['__construct']);
}

public function test_controllers_do_not_inject_repositories(): void
{
    $controllers = $this->layer()->leaveByNameStart('App\Controllers\');
    $repositories = $this->layer()->leaveByNameStart('App\Repositories\');

    // Controllers must not have repository type-hints in any method
    $this->assertIncomingsNotFrom($controllers, $repositories);
}
```

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

### Filter Layers by Object Type - PHPUnit Architecture Test

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Shows how to select specific object types like classes, interfaces, or traits to define layers. Includes examples for validating interface dependencies and trait usage patterns.

```php
use PHPUnit\Architecture\Enums\ObjectType;

public function test_interfaces_have_no_dependencies(): void
{
    // Get all interfaces in the project
    $interfaces = $this->layer()->leaveByType(ObjectType::_INTERFACE);

    // Get all concrete classes
    $classes = $this->layer()->leaveByType(ObjectType::_CLASS);

    // Interfaces should not depend on concrete classes
    $this->assertDoesNotDependOn($interfaces, $classes);
}

public function test_traits_usage_pattern(): void
{
    // Get all traits in the Concerns namespace
    $concerns = $this->layer()
        ->leaveByNameStart('App\Concerns\')
        ->leaveByType(ObjectType::_TRAIT);

    // Get domain models
    $models = $this->layer()->leaveByNameStart('App\Models\');

    // Models can use concern traits
    $this->assertDependOn($models, $concerns);
}
```

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

### PHP: Exclude Paths from Architecture Analysis

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

This example shows how to configure custom excluded paths for architecture analysis. By defining an `$excludedPaths` property in the test class, specific directories like 'src/Legacy' or 'src/External' are ignored during the layer analysis. This is crucial for managing refactoring efforts or integrating with external codebases.

```php
use Tests\TestCase;

class CustomArchitectureTest extends TestCase
{
    // Add custom excluded paths
    protected array $excludedPaths = [
        'src/Legacy',
        'src/External',
    ];

    public function test_modern_architecture(): void
    {
        // The layer() method will automatically exclude vendor/
        // plus your custom excluded paths
        $app = $this->layer()->leaveByNameStart('App\\');

        // Now $app excludes classes from src/Legacy and src/External
        $this->assertMethodSizeLessThan($app, 30);
    }
}

```

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

### Define Application Layers and Assert Dependencies (PHP)

Source: https://github.com/ta-tikoma/phpunit-architecture-test/blob/main/README.md

This snippet demonstrates how to define application layers using namespaces and assert dependency rules between them. It shows how to use `layer()` to create layers and `assertDoesNotDependOn` and `assertDependOn` to enforce architectural constraints.

```php
$controllers  = $this->layer()->leaveByNameStart('App\Controllers');
$services     = $this->layer()->leaveByNameStart('App\Services');
$repositories = $this->layer()->leaveByNameStart('App\Repositories');

$this->assertDoesNotDependOn($controllers, $repositories);
$this->assertDependOn($controllers, $services);
$this->assertDependOn($services, $repositories);
```

```php
$app = $this->layer()->leaveByNameStart('PHPUnit\Architecture');
$tests = $this->layer()->leaveByNameStart('tests');

$this->assertDoesNotDependOn($app, $tests);
$this->assertDependOn($tests, $app);
```

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

### Run PHPUnit Tests (Bash)

Source: https://github.com/ta-tikoma/phpunit-architecture-test/blob/main/README.md

This command executes all tests defined within your project using the PHPUnit test runner. It will include any architecture tests you have configured.

```bash
./vendor/bin/phpunit
```

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

### Split Layers with Custom Closure Logic

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Demonstrates splitting architectural layers using custom closure functions, allowing for grouping classes based on arbitrary criteria like directory depth or namespace structure beyond simple regex matching.

```php
public function test_split_by_custom_logic(): void
{
    // Split by directory depth or any custom criteria
    $layers = $this->layer()->split(
        function ($objectDescription) {
            // Group by top-level namespace component
            $parts = explode('\', $objectDescription->name);
            return $parts[1] ?? null; // Return layer name or null to exclude
        }
    );

    // Now $layers is an array of Layer objects grouped by namespace
}
```

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

### Split Layers into Multiple Groups by Regex

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Shows how to dynamically split a single architectural layer into multiple distinct layers based on regular expression patterns matching class names. This is useful for organizing code by feature or domain.

```php
public function test_feature_modules_do_not_cross_depend(): void
{
    // Split all classes into feature-based layers
    // Classes like App\Feature\Billing\Service and App\Feature\Auth\Controller
    // will be grouped into separate 'Billing' and 'Auth' layers
    $featureLayers = $this->layer()->splitByNameRegex(
        '/^App\\Feature\\(?<layer>[^\\]+)/'
    );

    // Each feature layer should not depend on other feature layers
    $this->assertDoesNotDependOn($featureLayers, $featureLayers);
}

public function test_split_domain_modules(): void
{
    // Split domain modules into separate layers
    $domainLayers = $this->layer()->splitByNameRegex(
        '/^App\\Domain\\(?<layer>[^\\]+)/'
    );

    // Optional: Each domain should be independent
    foreach ($domainLayers as $layerName => $layer) {
        // Custom validation per domain...
    }
}
```

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

### Extract Property Visibility and Method Names in PHP

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Demonstrates extracting specific attributes like property visibility or method names from objects within a layer using the `essence` method. This data can then be used for custom assertions, such as checking for readonly properties or naming conventions.

```php
public function test_all_properties_are_readonly(): void
{
    $valueObjects = $this->layer()->leaveByNameStart('App\ValueObjects\');

    // Extract all property visibility modifiers
    $visibilities = $valueObjects->essence('properties.*.visibility');

    // Custom assertion: each must be private or protected
    $this->assertEach(
        $visibilities,
        fn($visibility) => in_array($visibility, ['private', 'protected']),
        fn($key, $visibility) => "Property $key has invalid visibility: $visibility"
    );
}

public function test_extract_method_names(): void
{
    $repositories = $this->layer()->leaveByNameStart('App\Repositories\');

    // Extract all method names
    $methodNames = $repositories->essence('methods.*.name');

    // Verify naming conventions
    $this->assertEach(
        $methodNames,
        fn($name) => !str_starts_with($name, '_'),
        fn($key, $name) => "Method $name should not start with underscore"
    );
}
```

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

### PHP: Validate Complete Layered Architecture

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

This snippet demonstrates how to define architectural layers (Controllers, Services, Repositories, Models, DTOs) and enforce dependency rules between them. It also includes checks for method size and public properties, ensuring encapsulation and type safety. This test is useful for maintaining strict separation of concerns in a layered application.

```php
public function test_complete_layered_architecture(): void
{
    // Define all architectural layers
    $controllers  = $this->layer()->leaveByNameStart('App\\Http\\Controllers\\');
    $services     = $this->layer()->leaveByNameStart('App\\Services\\');
    $repositories = $this->layer()->leaveByNameStart('App\\Repositories\\');
    $models       = $this->layer()->leaveByNameStart('App\\Models\\');
    $dtos         = $this->layer()->leaveByNameRegex('/DTO$/');

    // Dependency rules: Controllers â→ Services â→ Repositories â→ Models
    $this->assertDependOn($controllers, $services);
    $this->assertDoesNotDependOn($controllers, $repositories);
    $this->assertDoesNotDependOn($controllers, $models);

    $this->assertDependOn($services, $repositories);
    $this->assertDependOn($repositories, $models);

    // Method complexity rules
    $this->assertMethodSizeLessThan($controllers, 20);
    $this->assertMethodSizeLessThan($services, 50);

    // Encapsulation rules
    $this->assertHasNotPublicProperties($models);
    $this->assertHasNotPublicProperties($services);

    // Type safety rules
    $this->assertIncomingsFrom($services, $repositories, ['__construct']);
    $this->assertOutgoingFrom($repositories, $models);

    // DTOs can be used everywhere
    $this->assertDependOn([$controllers, $services, $repositories], $dtos);
}

```

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

### Exclude Classes with Custom Closures

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Illustrates how to use custom closure functions to define exclusion or inclusion criteria for classes within architectural layers. This allows for more complex filtering logic based on class properties.

```php
public function test_exclude_with_closure(): void
{
    // Exclude abstract classes from analysis
    $concreteClasses = $this->layer()->exclude(
        function ($objectDescription) {
            return str_contains($objectDescription->name, 'Abstract');
        }
    );

    // Or keep only specific classes
    $dtoClasses = $this->layer()->leave(
        function ($objectDescription) {
            return str_ends_with($objectDescription->name, 'DTO');
        }
    );
}
```

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

### Validate Each PHP Controller Follows Naming Convention

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Uses the `assertEach` custom iterator assertion to verify that all controller names within a specified namespace end with the 'Controller' suffix. This helps maintain consistent naming practices.

```php
public function test_each_controller_follows_naming(): void
{
    $controllers = $this->layer()->leaveByNameStart('App\Controllers\');

    $controllerNames = array_map(
        fn($obj) => $obj->name,
        iterator_to_array($controllers)
    );

    // Each controller name must end with 'Controller'
    $this->assertEach(
        $controllerNames,
        fn($name) => str_ends_with($name, 'Controller'),
        fn($key, $name) => "Controller $name must end with 'Controller' suffix"
    );
}
```

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

### Integrate Architecture Assertions Trait (PHP)

Source: https://github.com/ta-tikoma/phpunit-architecture-test/blob/main/README.md

This PHP code shows how to integrate the `ArchitectureAsserts` trait into your custom TestCase class. By using this trait, your test classes gain access to the architectural assertion methods provided by the library.

```php
abstract class TestCase extends BaseTestCase
{
    use ArchitectureAsserts;
}
```

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

### Exclude Classes from Layers by Name or Regex

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Demonstrates how to exclude specific classes from architectural layer definitions using name prefixes or regular expressions. This is useful for ignoring legacy code or test-specific classes.

```php
public function test_services_except_legacy(): void
{
    // Get all services except legacy ones
    $modernServices = $this->layer()
        ->leaveByNameStart('App\Services\')
        ->excludeByNameStart('App\Services\Legacy\');

    // Get repositories
    $repositories = $this->layer()->leaveByNameStart('App\Repositories\');

    // Modern services must use repositories
    $this->assertDependOn($modernServices, $repositories);
}

public function test_exclude_by_regex(): void
{
    // Get all controllers except test/example ones
    $productionControllers = $this->layer()
        ->leaveByNameStart('App\Controllers\')
        ->excludeByNameRegex('/Test|Example/');

    // Production controllers must not have Test/Example dependencies
    $testHelpers = $this->layer()->leaveByNameRegex('/Test|Example/');
    $this->assertDoesNotDependOn($productionControllers, $testHelpers);
}
```

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

### Ensure at Least One Factory Service Exists in PHP

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Utilizes the `assertAny` custom iterator assertion to confirm that at least one service within the `App\Services` namespace contains 'Factory' in its name, verifying the presence of necessary factory patterns.

```php
public function test_at_least_one_factory_exists(): void
{
    $services = $this->layer()->leaveByNameStart('App\Services\');

    $serviceNames = array_map(
        fn($obj) => $obj->name,
        iterator_to_array($services)
    );

    // At least one factory service must exist
    $this->assertAny(
        $serviceNames,
        fn($name) => str_contains($name, 'Factory'),
        'No factory service found in App\Services namespace'
    );
}
```

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

### Limit Method Size in PHP Services and Controllers

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Enforces maximum method line counts for classes within specified namespaces (e.g., Services, Controllers) to maintain code readability and maintainability. Uses `assertMethodSizeLessThan` for validation.

```php
public function test_service_methods_not_too_large(): void
{
    $services = $this->layer()->leaveByNameStart('App\Services\');

    // No method in services should exceed 30 lines
    $this->assertMethodSizeLessThan($services, 30);
}

public function test_controller_methods_are_thin(): void
{
    $controllers = $this->layer()->leaveByNameStart('App\Controllers\');

    // Controllers should be thin (max 20 lines per method)
    $this->assertMethodSizeLessThan($controllers, 20);
}
```

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

### Enforce Property Visibility in PHP Models and DTOs

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Ensures encapsulation by asserting that domain models and Data Transfer Objects (DTOs) do not expose public properties. Utilizes the `assertHasNotPublicProperties` method for validation.

```php
public function test_domain_models_have_no_public_properties(): void
{
    $models = $this->layer()->leaveByNameStart('App\Models\');

    // Domain models must not expose public properties
    // This enforces proper encapsulation
    $this->assertHasNotPublicProperties($models);
}

public function test_dtos_encapsulation(): void
{
    $dtos = $this->layer()->leaveByNameRegex('/DTO$/');

    // Even DTOs should not have public properties
    $this->assertHasNotPublicProperties($dtos);
}
```

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

### Prevent God Objects in PHP Classes

Source: https://context7.com/ta-tikoma/phpunit-architecture-test/llms.txt

Employs the `assertNotOne` custom iterator assertion to ensure that no class in the codebase exceeds a predefined method count (e.g., 20 methods), thus preventing the 'god object' anti-pattern.

```php
public function test_no_god_objects(): void
{
    $allClasses = $this->layer()->leaveByType(ObjectType::_CLASS);

    $methodCounts = array_map(
        fn($obj) => ['name' => $obj->name, 'count' => count($obj->methods)],
        iterator_to_array($allClasses)
    );

    // No class should have more than 20 methods (god object anti-pattern)
    $this->assertNotOne(
        $methodCounts,
        fn($data) => $data['count'] > 20,
        fn($key, $data) => "Class {$data['name']} has {$data['count']} methods (max 20)"
    );
}
```
Tokens:
Raw