/api-ddd-template

API template with DDD and Hexagonal architecture

Primary LanguagePHPMIT LicenseMIT

api-ddd-template

  1. About project
  2. Set up project
  3. Unit Tests
  4. Code Quality Checker Tools
  5. Code Analysis Tools
  6. Documentation
  7. Future improvements

About project

  • Symfony 4.4
  • Docker with PHP 8 and MySQL 5.7 containers
  • Makefile
  • Packages installed: Symfony Flex, Doctrine, Security, NelmioApiDocBundle, MakerBundle, DoctrineFixturesBundle and PHPUnit among others
  • DDD and Hexagonal architecture
  • Best practices: Clean code, PHP Standards Recommendations (PSR), SOLID principles and design patterns
  • Unit tests: PHP Unit
  • Code Quality Checker Tools: PHP_CodeSniffer, PHPStan, PHP Mess Detector, PHP Magic Number Detector, PHP Copy Paste Detector, Churn-php, PhpDeprecationDetector, Twigcs
  • Code Analysis Tools: Deptrac
  • Exceptions handler
  • Database full dump with test data included in migrations folder

Set up project

If not already done, install Docker Compose before continue with installation.

Installation

Clone repository:

git clone https://github.com/burus86/api-ddd-template.git

cd api-ddd-template

Build and up docker containers:

make start

Install composer dependencies:

make install

Configure environment variables

Rename filename .env.dist as .env and edit DATABASE_URL value with database parameters

Open filename .env.test and edit DATABASE_URL value with test database parameters.

Create database

Execute the following commands to create an empty database with the name specified in .env filename:

make bash

php bin/console doctrine:database:create

php bin/console doctrine:schema:update --force

Execute the following command in order to dump fake data in database tables:

php bin/console doctrine:fixtures:load

Alternatively, you can either import the db-api-ddd-template-full.sql file, included in migrations folder, to create and populate the database schema, however this file might not be up to date.

docker exec -it api-ddd-template_db bash

mysql -uroot -p

create database db_api_ddd_template;

exit;

mysql -uroot -p db_api_ddd_template < /var/backups/db-api-ddd-template-full.sql

Execute project

Open in your favorite web browser the website http://localhost:8080/api/doc.

All API endpoints require a X-AUTH-TOKEN in header, with a value equal to field api_token in user table. Example: cU70Sbr0qKrUQHE0tw60XQVMwBP8hJrdRMY61xhX

Captura

Captura

Execute all tests

To run all the tests (unit tests, code quality checker tools and code analysis tools), just execute the command make test with option -i or --ignore-errors:

make test -i

If you prefer, it's also possible to run each individual test following the instructions below.

Unit Tests

PHP Unit

make test-phpunit

Code Quality Checker Tools

Source:

PHP_CodeSniffer

make test-phpcs

In order to automatically correct coding standard violations, execute:

make test-phpcbf

PHPStan

make test-phpstan

PHP Mess Detector

make test-phpmd

PHP Magic Number Detector

make test-phpmnd

PHP Copy Paste Detector

make test-phpcpd

Churn-php

churn-php is a package that helps you identify php files in your project that could be good candidates for refactoring.

make test-churn

PhpDeprecationDetector

make test-phpdd

Twigcs

make test-twigcs

Code Analysis Tools

Deptrac

make test-deptrac

Documentation

The easiest way to generate full project documentation is by running the following command:

php phpDocumentor.phar -d src -t public/docs

Once generated, you can check the documentation under http://localhost:8080/docs in your favorite web browser.

Captura

Future improvements