README.md

Explicit Architecture

Symfony Demo Application

The "Symfony Demo Application" is a reference application created to show how to develop Symfony applications following the recommended best practices.

This repository is a demo of Explicit Architecture, using the Symfony Demo Application.

There is code in this project that not used and therefore it would be removed in a real project, nevertheless it was included here as examples.

Explicit Architecture

I explained Explicit Architecture in one of my blog posts, as a result of my understanding of several architectural ideas such as (but not limited to) EBI Architecture, DDD, Ports & Adapters Architecture, Onion Architecture and Clean Architecture.

Package by component

Dependencies directions

Folder structure

• bin (application binaries, however the dependencies binaries should go in vendor/bin)
• build (artifacts needed for building the application prior to running it)
• config (all the config needed to run the application)
• docs (application documentation)
• lib (libraries used by the application, which are specific to this application and/or not distributable)
  • php-extension (code to be used as if it was part of the language itself)
    • src
    • tests
• public (the entry point to the application, and public frontend artifacts like CSS and JS files)
• src
  • Core (the application core)
    • Component (the application components/bounded contexts)
    • Port (the ports, to be implemented by the infrastructure adapters)
    • SharedKernel (application and domain code shared among all components/bounded contexts)
  • Infrastructure (the port adapters for the infrastructure tools)
  • Presentation (the presentation layer with the several user facing applications, controllers, views and related code units)
    • Console (the CLI UI)
    • Web (the web UI)
      • Core (the web UI core)
        • Component (the web UI core components)
        • Port (the web UI core ports, used only in the web UI)
      • Infrastructure (the web UI infrastructure, used only in the web UI)
• tests
  • Fixture (data to put in the DB and use in the tests)
  • Framework (support code to run the tests, like base test classes and assertions)
  • TestCase (unit, integration, functional, acceptance tests, with only one folder tree mimicking the src folder)
• translations
• var (volatile artifacts like logs, cache, temporary test databases, generated code, ...)
• vendor (distributable libraries)

Dependencies testing and documentation

Since the code organization, its structure, is quite explicit we can easily have an architectural integrity test suite to make sure we are not breaking the architecture.

This project architectural integrity test suite consists of three tests, which are executed using deptrac. Deptrac can also generate some nice graphs with the dependencies tree, which makes it great as a documentation artifact.

1. Layer dependencies integrity

   This tests the code layers dependency integrity, making sure the dependencies always goes inwards, when matched to the layers in the Explicit Architecture diagram on top.

   

2. Component dependencies integrity

   This test makes sure that the components are decoupled between them.

   

3. Class type dependencies integrity

   This test goes to a class level dependency integrity check, specially useful for classes in the same layer and component. For example, the application services, query objects and repositories all belong to the Application Layer, and they all exist within each component. However, there are rules that must be followed:

   1. A service can depend on query objects and repositories;
   2. A query object should not depend on a service nor a repository,
   3. A repository should not depend on a service nor a query object.
   4. And, of course, none of them should depend on a controller, although that can be tested using the layers dependency test, because the controllers belong in the UI layer.

   

Usage

You need to have docker installed in your host OS.

Execute the following commands to prepare the project locally:

$ composer install
$ make box-build-prd
$ make dep_analyzer-install

Execute this command to run the tests suite:

$ make test

Execute this command to run the app in dev mode:

$ make up

or this command to run the app in production mode:

$ make up-prd

Access the application in your browser at http://localhost:8000.

You can also test the error pages at http://localhost:8000/index.php/_error/{statusCode}.{format}, ie. http://localhost:8000/index.php/_error/400.html.

To see all commands available run:

$ make

Tests

To be able to run the architecture integrity tests, you first need to install deptrac:

$ make dep_analyzer-install

Execute this command to run tests:

$ make test

Or this command to run tests and get the coverage:

$ make test_cov

Integration with PHPStorm

Integration with PHPStorm is straight forward.

Configure the servers so we can debug a request made from the browser:

Configure the CLI so we can run the tests:

Configure the test run itself:

Debug

The dev container has xDebug installed and you can use it out of the box, provided that you have your IDE configured appropriately.

Check the screenshots in the docs/IDE/PHP_Storm/ folder, to check how to configure PHP Storm to work with xDebug, as it is set up in the dev docker image.

To run the tests with xDebug enabled, you need to enable it in container/tst/xdebug.ini:1 prior to running the tests.