arkitect

Project Overview

PHPArkitect is a powerful tool designed to maintain a clean and consistent architecture within PHP codebases. It allows developers to introduce architectural constraints into their workflow, ensuring code coherence and integrity. Using straightforward PHP syntax, developers can define rules to enforce naming conventions, dependencies, and structure, making it a valuable asset for maintaining project quality.

Installation

Developers can integrate PHPArkitect into their projects using Composer, a popular dependency manager for PHP. This method is straightforward, requiring the addition of PHPArkitect as a development dependency:

composer require --dev phparkitect/phparkitect

Alternatively, PHPArkitect offers a Phar file for projects that might have dependency conflicts. This self-contained PHP executable can be downloaded from GitHub:

wget https://github.com/phparkitect/arkitect/releases/latest/download/phparkitect.phar
chmod +x phparkitect.phar
./phparkitect.phar check

Usage

To utilize PHPArkitect, users primarily work through the command line. The check command triggers rule verification on the codebase, allowing users to specify configuration files with the --config option. A progress bar indicates the status of the analysis.

Handling Violations

PHPArkitect offers a baseline feature to manage violations. Users can generate a baseline file containing current violations using:

phparkitect check --generate-baseline

This helps in ignoring pre-existing violations while focusing on new ones. The tool allows flexibility in managing baseline files, including the option to ignore line numbers during checks.

Configuration

Rules are defined in a configuration file (phparkitect.php). This file uses PHP syntax to specify the rule logic. For instance, developers can restrict classes within a namespace to follow a certain naming pattern or restrict dependencies to specific namespaces.

Here’s a sample configuration:

<?php
declare(strict_types=1);

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

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

    $rules = [];

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

    $rules[] = Rule::allClasses()
        ->that(new ResideInOneOfTheseNamespaces('App\Domain'))
        ->should(new NotHaveDependencyOutsideNamespace('App\Domain'))
        ->because('we want to protect our domain');

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

Available Rules

PHPArkitect supports a variety of rules to enforce different constraints. These include checks for dependencies, naming patterns, class hierarchy, and more. Users can create complex logical conditions using the provided expressions and builders.

Examples of Rule Assertions

• Ensuring classes in a namespace depend only on certain other namespaces.
• Verifying that class names match specific patterns.
• Checking for or against the implementation of interfaces.
• Confirming class attributes.

Rule Builders

PHPArkitect includes builders to facilitate clearer rule definitions. For example, the Component Architecture Rule Builder allows defining components and setting dependency constraints in a structured way. This makes maintaining architecture more readable and manageable.

Integrations

For developers using Laravel, there is an available integration, developed by smortexa, which includes predefined rules tailored to Laravel applications. This integration aims to simplify applying PHPArkitect in Laravel environments.

Summing up, PHPArkitect is an essential tool for PHP developers focused on maintaining a consistent code architecture, enabling them to define and enforce custom rules that align with project-specific requirements.