Clean architecture php example

Saved searches

Use saved searches to filter your results more quickly

You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session.

Simple PHP application following Clean Architecture principles

gushakov/clean-php

This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Sign In Required

Please sign in to use Codespaces.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching GitHub Desktop

If nothing happens, download GitHub Desktop and try again.

Launching Xcode

If nothing happens, download Xcode and try again.

Launching Visual Studio Code

Your codespace will open once ready.

There was a problem preparing your codespace, please try again.

Latest commit

Git stats

Files

Failed to load latest commit information.

README.md

Clean Architecture in a PHP application

This application is based on the example application by Kevin Smith. Here is the related GitHub repository containing the original source code. Please, consult the copyright and licence notices distributed with the orignal code by Kevin Smith.

There is an article on Medium: «Clean Architecture with PHP», which references this repository.

The idea is to build a relatively simple PHP application but without using any framework. I followed closely the recipe given in a wonderful and very detailed article by Kevin Smith.

In addition, the application is so structured as to illustrate the most important principles of Clean Architecture and Use Case driven development. The application itself is a variation of a Hello World, but with a following additions:

• greetings are displayed randomly
• greeting messages are persisted in a local database
• each greeting has an author associated with it
• an authenticated user can edit the author of any greeting

There is an excellent video by Nicolas De Boose explaining benefits of using Clean Architecture specifically for PHP development. I highly recommend it.

1. Hexagonal or «Ports and Adapters» architecture
2. All dependencies are directed towards the core, «outside-in»
3. Core is completely independent of the infrastructure
4. Clean Architecture based on explicit use cases
5. DDD modeling: Entities, Value Objects
6. Immutable objects
7. Repository pattern
8. Testable core
9. Domain exceptions hierarchy

• Requires PHP 8.1 or later
• See \ExampleApp\Infrastructure\Application\AppConfig::$props global array for configurations
• Run a development server from the IDE:

> php.exe -S localhost:8080 -t public/ 

Clean Architecture metrics

There is a wonderful project by Valeriy Chetkov on GitHib: php-clean-architecture. It allows to measure how «clean» the architecture of an application is.

You can try to run this script to check if all dependencies are going from outside («infrastructure») in («core»):

> php.exe .\vendor\bin\phpca-check .\phpca-config.php 

You can also check out other interesting metrics by running either of the following scripts:

> php.exe .\vendor\bin\phpca-build-reports .\phpca-config.php 

> php.exe .\vendor\bin\phpca-build-reports .\phpca-config-all.php 

To visualize reports, simply open the generated phpca-reports/index.html in a browser.

About

Simple PHP application following Clean Architecture principles

Источник

PHPCleanArchitecture — Что нового?

Этот пост является дополнением предыдущего. В нём я расскажу о новых возможностях инструмента (с блэкджеком и шлюпками с примерами и картинками).

Предисловие

Привет! Рад что ты читаешь это, а еще больше я буду рад, если этот пост окажется для тебя интересным и полезным.

В своём предыдущем посте я представил сообществу инструмент для визуализации и анализа архитектуры php-приложений и автоматизации процесса контроля её качества.

С тех пор прошло не мало времени и мне есть чем поделиться.

Сегодня поговорим о новых возможностях, без которых использование php-clean-architecture в реальных проектах было сильно затруднено (или вообще невозможно).

Если бы мне кто-то сказал, что в проекте над которым он трудится продолжительное время (с командой или в одиночку, наверное не важно), нет архитектурных проблем — я бы не поверил. И дело здесь совсем не в компетенции команды или конкретных её членов, а в человеческом факторе.

Человек без ошибки — ошибка природы. (Когда-то давно, в моём детстве, так мне говорил отец).

Мы люди, а людям свойствено ошибаться: разработчик допустил ошибку, ревьюер недоглядел и пропустил запрос на слияние, и вот проблема уже в мастере.

А ты ведь знаешь — архитектурные ошибки коварны. Они могут очень долгое время оставаться незамеченными, а проявляются (по собственному опыту) в самый неподходящий момент.

Автоматизация — самый действенный способ решения многих проблем. Мне кажется, если процесс контроля качества кода/архитектуры в проекте не автоматизирован (средствами различных инструментов, вроде стат. анализаторов и их подобным), в нём просто не может не быть проблем.

Об автоматизации процесса контроля качества архитектуры php-проектов я рассказывал во второй части предыдущего поста. Наглядно и с примерами я показывал, как подключить и начать использовать разработанный мною инструмент php-clean-architecture (далее по статье — phpca). С его помощью можно визуализировать граф зависимости компонентов проекта и контролировать значения метрик качества, описанных Робертом Мартиным в его книге «Чистая архитектура».

Разрешенное состояние проекта

Как оказалось, тогда phpca был хорош при подключении к проектам на начальном этапе. В таких проектах еще нет большого тех. долга, а значит все обнаруженные проблемы можно махом исправить, и дальше уже сам phpca будет бить разработчиков по рукам. Но вот при подключении его к боевому проекту выяснилось, что гибкости для работы с большими проектами, в которых уже накоплен внушительный тех. долг, что разом исправить его за сколь-либо адекватный срок невозможно, сильно не хватает.

Пример: предположим есть проект состоящий из следующих компонентов:

• domain (сущности, интерфейсы их репозиториев, . )
• infrastructure (какие-то инфраструктурные классы, типа email и sms сендеров, реализации репозиториев, . )
• use cases (различные возможные сценарии использования)
• entry-points (классы запросов и ответов, контроллеры, форматеры и прочее)

Каждый из компонентов содержит 100+ файлов.

Настраивая phpca мы задаём правила:

• domain не должен иметь исходящих зависимостей
• use cases может знать только про domain
• entry-points может знать только про use-cases и domain
• infrastructure может знать только про domain и use cases

• 20 классов из domain каким-либо образом зависят от 17 классов из use cases
• 32 класса из use case используют 28 сервисов из infrastructure
• 18 контроллеров из entry-points используют 12 классов из infrastructure
• и даже сервисы из infrastructure зависят от request-классов из entry-points

(не спрашивай почему так, пример надуманный, но даёт возможность предметно рассмотреть проблему и ее решение)

Что получается? С одной стороны мы не можем быстро решить все обнаруженные проблемы, их слишком много. С другой стороны, если сейчас не задать запрещающие правила для направлений в графе зависимости компонентов, то через время проблем будет еще больше.

Для решения этой проблемы в инструмент была добавлена команда сохранения текущего состояния проекта (настройка доступна в конфигурационном файле phpca-config.php)

// Исключения 'exclusions' => [ 'allowed_state' => [ 'enabled' => true, 'storage' => __DIR__ . '/phpca-allowed-state.php', ], ],

В процессе выполнения, команда vendor/bin/phpca-allow-current-state строит и сохраняет нынешний граф зависимости компонентов и их составляющих между собой для его дальнейшего использования.

При истинном значении флага exclusions.allowed_state.enabled, в момент выполнения команд phpca-build-report и phpca-check, ранее сохраненное разрешенное состояние проекта будет учитываться анализатором, и ранее существовавшие несоответствия в графе зависимости компонентов будут игнорироваться.

Таким образом, мы можем взять абсолютно любой проект, с любым количеством проблем, подключить и настроить в нем phpca как нам хочется, выгрузить текущее состояние и сразу запускать его в эксплуатацию. Старые проблемы будут игнорироваться, но новые phpca уже не пропустит. А далее, по мере решения старых проблем, усиливать проверки.

Рекоммендация: Файл для сохранения разрешенного состояния проекта должен быть под управлением системы контроля версий (для того, чтоб у всех членов команды он был един, а еще для возможности частичного построения отчетов или запуска проверок по списку разрешенных путей, но об этом в следующем пункте).

Ограничение работы списком разрешенных путей

В какой-то из дней, сидя на работе и отсматривая одну жирную MR коллеги, я задался вопросом.. Запрос на слияние был действительно большим и мне хотелось взглянуть на изменения сверху, без лишних деталей. Тогда я уже использовал phpca в нескольких проектах, но он мог работать только со всей кодовой базой, а я хотел визуализировать лишь ее новую/измененную часть. Ведь это было бы очень удобно, иметь возможность еще на этапе код-ревью, за пару секунд сформировать по измененным файлам отчет без воды и лишних деталей, с визуализацией графа зависимости компонентов и таблиц зависимости их составляющих, и понять какие из этих изменений и чем нарушают установленные правила.

Еще хотелось сделать эту возможность гибкой, чтоб списки разрешенных путей можно было формировать и передавать в команду динамически. Конфигурационный файл для этих целей не подходил чуть больше чем совсем. Так phpca научился работать с переменными окружения.

Рассмотрим пример: ниже расположен общий граф зависимости компонентов php-clean-architecture, построенный командой vendor/bin/phpca-build-reports по всей кодовой базе проекта

Далее рассмотрим детали со страницы отчета по компоненту entry-points

(я специально выбрал в качестве примера небольшой компонент небольшого проекта, чтоб всё было максимально наглядно и не возникло путаницы)

На скриншоте видно, что изначально 1 класс из entry-points зависит от 4х классов из model.

Далее я внесу некоторые бессмысленные изменения в entry-points и сформирую отчет на основании этих изменений.

export PHPCA_ALLOWED_PATHS=`git diff master --name-only` PHPCA_REPORTS_DIR='phpca-reports-by-git-diff'; bin/phpca-build-reports

Общий граф зависимости компонентов и граф зависимостей entry-points теперь выглядят одинаково. (Это происходит из-за того, что текущий отчет отображает данные только из единственного измененного файла, лишние компоненты из основного графа убраны)

На скриншоте видно, что в таблице зависимости составляющих компонента, помимо ранее существовавших теперь стали отражены и вновь внесенные изменения, а лишние компоненты и их составляющие из отчета убраны.

Так было уже почти хорошо, но мне все еще хотелось больше гибкости. Хотелось отбросить больше лишнего и оставить только самое важное. Ведь видеть полный отчет только по измененным файлам — это круто, но иногда было бы полезно видеть по измененным файлам НЕ полный отчет. Зачем мне смотреть список всех зависимостей, пусть даже и только измененных файлов, если я хочу узнать какие зависимости были добавлены в текущей ветке?

Это можно было реализовать дополнив фильтрацию графа по списку разрешенных путей, проверками наличия зависимостей в разрешенном состоянии проекта (из предыдущего пункта статьи).

Ниже я включу в файле конфигурации флаг exclusions.allowed_state.enabled и повторно сформирую отчет на основании git diff текущей ветки с master.

Теперь граф и таблица зависимостей отображают только те изменения, которые действительно были внесены в измененных файлах. Все остальное из отчета убрано и это как-раз тот результат который мне хотелось получить.

Заключение

Используя описанные выше возможности ты можешь сильно упростить процесс подключения phpca к своему проекту, даже если он активно разрабатывается большой командой и в нем есть много легаси, а также начать использовать инструмент при проведении код-ревью сессий, и таким образом благодаря наглядности облегчить анализ больших запросов на слияние и поиск в них потенциальных архитектурных проблем.

Я искренне рад, что ты дочитал пост до этого места. Спасибо тебе за потраченное время, и я надеюсь что возможность использования phpca и знания приобретенные из этой статьи в дальнейшем сэкономят тебе намного больше времени.

А еще я буду очень рад получить твою обратную связь в ЛС или комментариях.

Доброго времени суток и чистой архитектуры!

Источник