Mastering Architectural Rules in PHP Projects with PHP Arkitect

How to Use PHP Arkitect to Define, Enforce, and Maintain Clean Code Structures

Photo by Tingey Injury Law Firm on Unsplash

Maintaining architecture in PHP projects can be a challenge, especially as projects scale.

PHP Arkitect is a powerful tool that allows developers to define architectural rules for their code, enforcing consistent structure and keeping dependencies in check.

In this article, we’ll explore the benefits of PHP Arkitect, guide you through its installation and usage, and show you how to implement it in your projects.
By the end, you’ll have a robust understanding of PHP Arkitect and its role in keeping your PHP codebase maintainable and aligned with architectural principles.

Why Architecture Matters

As your application grows, so does the complexity of its structure.

Without architectural constraints, a project can quickly become difficult to maintain. With increased dependencies, varied design patterns, and developers joining or leaving, it’s easy for an application to drift from its original design principles
This is where PHP Arkitect comes in: it allows developers to define and enforce architectural rules, keeping the code consistent and maintainable over time.

Getting started

By codifying architecture, it helps avoid common pitfalls and keeps the project in line with design goals. Let’s get into how PHP Arkitect works and see how you can set it up in your project to improve maintainability.

Installation
Install the PHP Arkitect package using composer:
composer require --dev phparkitect/phparkitect

Create the phparkitect.php file
Arkitect rules should be defined in this file, which will be read when executing the tool.
It searches for the phparkitect.php file by default.

Here is how a basic configuration file looks like:

<?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 {
    $srcClassSet = ClassSet::fromDir(__DIR__.'/src');

    $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\Entity'))
        ->should(new NotHaveDependencyOutsideNamespace('App\Entity'))
        ->because('we want protect our domain');

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

This file enforces two basic standards:

• Every Controller class in the App\Contrroller namespace should have a name that ends with Controller
• Every class in the App\Entity namespace should only depend on other classes from the same namespace, protecting your Entities from the rest of the codebase.

As you can see, it is pretty easy to define standards this way, and it can be done quite extensively!

You could for example define rules that disallow the using of persistence layers in Factory classes, or Controllers, or more…

This file can be automatically generated using vendor/bin/phparkitect init.

Running PHP Arkitect

You’re good to go: the tool is installed, the configuration works fine, let’s analyze our code!

Run Arkitect using vendor/bin/arkitect check, (or phparkitect check if you’re using the Phar Installation).

The PHP Arkitect check command output, no violations.

It is as simple as it gets!

Advanced Rules and Customization

PHP Arkitect offers powerful features for complex applications. Beyond basic namespace dependencies, you can define rules for class naming conventions, method visibility, and more. Customization options include:

• Enforcing patterns like Service suffixes for service classes.
• Restricting certain classes from implementing specific interfaces.
• Limiting dependencies to specific packages or modules.

These features let you tailor PHP Arkitect to fit your project’s unique architectural needs.

PHP Arkitect’s limits

While PHP Arkitect is highly effective, it’s not without limitations. Crafting rules requires a deep understanding of your project’s architecture, and overly strict rules may stifle flexibility.

Moreover, legacy codebases might need refactoring before introducing PHP Arkitect, as they might not immediately conform to clean architectural principles.

PHP Arkitect offers a powerful way to enforce architectural rules within PHP projects, helping maintain code quality and structure as applications grow.

By defining clear guidelines and integrating PHP Arkitect into your workflow, you can create a maintainable and scalable codebase.

While not a silver bullet, PHP Arkitect is an essential tool for any PHP developer focused on proper architecture.

You can find more about this tool in its GitHub’s page.

If you liked this article, check my other posts or follow my account, you might find something interesting!

As always, have a good day 🤩