README

PHPArkitect lets you write architectural rules for your PHP codebase as plain PHP code and verify them in CI. Think of it as a test suite for your architecture: if a class in App\Domain imports something from App\Infrastructure, the check fails.

Rule::allClasses()
    ->that(new ResideInOneOfTheseNamespaces('App\Domain'))
    ->should(new NotHaveDependencyOutsideNamespace('App\Domain'))
    ->because('the domain must not depend on infrastructure');

Upgrading from an older version? Check UPGRADE.md for breaking changes.

Quick Start

1. Install

composer require --dev phparkitect/phparkitect

2. Create a config file

vendor/bin/phparkitect init

This scaffolds phparkitect.php in the current directory. Edit it to add your rules.

3. Run

vendor/bin/phparkitect check

PHPArkitect reports every violation with the class name, the broken rule, and the ->because() message you wrote.

Core concepts

A minimal config file:

<?php
declare(strict_types=1);

use Arkitect\ClassSet;
use Arkitect\CLI\Config;
use Arkitect\Expression\ForClasses\HaveNameMatching;
use Arkitect\Expression\ForClasses\ResideInOneOfTheseNamespaces;
use Arkitect\Rules\Rule;

return static function (Config $config): void {
    $classSet = ClassSet::fromDir(__DIR__.'/src');

    $rules[] = Rule::allClasses()
        ->that(new ResideInOneOfTheseNamespaces('App\Controller'))
        ->should(new HaveNameMatching('*Controller'))
        ->because('we want uniform naming for controllers');

    $config->add($classSet, ...$rules);
};

PHPArkitect parses custom DocBlock annotations (@Assert\NotBlank, etc.) by default; call $config->skipParsingCustomAnnotations() to disable this.

Available rules

📖 Full rules reference →

Commands

check

phparkitect check

Looks for phparkitect.php in the current directory by default. Use --config to point to a different file:

phparkitect check --config=/project/yourConfigFile.php

init

Scaffolds a phparkitect.php so you don't have to write it from scratch:

phparkitect init [--dest-dir=<path>]

If a phparkitect.php already exists, the command leaves it untouched.

debug:expression

Lists which classes in a directory satisfy a given expression — handy for testing a rule before adding it to your config:

phparkitect debug:expression <Expression> [arguments...]

<Expression> is the short class name of any expression under Arkitect\Expression\ForClasses (see docs/rules.md); arguments match its constructor. For example:

phparkitect debug:expression ResideInOneOfTheseNamespaces App

Configuration reference

Every setting can be passed as a CLI option or set via the corresponding Config method. When both are set, the CLI option wins.

Baseline

If your codebase already has violations you can't fix right now, generate a baseline to ignore them:

phparkitect check --generate-baseline

This creates phparkitect-baseline.json. Subsequent runs pick it up automatically. Use a custom file name with --generate-baseline=my-baseline.json, point to it with --use-baseline=my-baseline.json, or skip it entirely with --skip-baseline.

By default the baseline also checks line numbers — a change before the offending line shifts the number and the check fails. Use --ignore-baseline-linenumbers to match violations regardless of line number.

Warning: when ignoring line numbers, PHPArkitect cannot detect if the same rule is violated additional times in the same file.

Output format

Using a Phar

If your project conflicts with PHPArkitect's dependencies, use the self-contained Phar:

wget https://github.com/phparkitect/arkitect/releases/latest/download/phparkitect.phar
chmod +x phparkitect.phar
./phparkitect.phar check --autoload=vendor/autoload.php

The --autoload option is required for all Phar runs.

Upgrading

Upgrading from an older version? See UPGRADE.md for the breaking changes you need to address.

Contributing

Found a bug or missing information? Open an issue. Want to contribute? See CONTRIBUTING.md.