api-ddd-template

1. About project
2. Set up project
   • Installation
   • Configure environment variables
   • Create database
   • Execute project
   • Execute all tests
3. Unit Tests
   • PHP Unit
4. Code Quality Checker Tools
   • PHP_CodeSniffer
   • PHPStan
   • PHP Mess Detector
   • PHP Magic Number Detector
   • PHP Copy Paste Detector
   • Churn-php
   • PhpDeprecationDetector
   • Twigcs
5. Code Analysis Tools
   • Deptrac
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

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:

• https://thevaluable.dev/code-quality-check-tools-php/
• https://github.com/collections/code-quality-in-php

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.

Future improvements

• Upgrade PHP to latest stable version: 8.0
• Add docker configuration files
• Upgrade Symfony to latest stable version: 5.3
• Add JWT authentication, which replace current API Key defined in user
• Create application tests, to check the integration of all the different layers of the application.
• Install serializer component to normalize objects as JSON and hide specific fields
• Use DoctrineMigrationsBundle
• Add uuid field for each model and hide id field on JSON responses