PHP Symfony environment with a JSON REST API

A scalable Docker-based environment (based on official PHP and MySQL Docker Hub repositories) required to run Symfony with a JSON REST APIs.

Source code

This repository provides a basic (lite) DDD foundation and the standard core logic. If you are looking for a cleaner, pragmatic DDD architecture, a superior environment with robust core logic, and flawless documentation, we highly recommend our commercial product Enterprise API.

Requirements

• Docker Engine version 23.0 or later
• Docker Compose version 2.0 or later
• An editor or IDE
• MySQL Workbench

Note: We recommend using a Linux Ubuntu-based OS for the best experience.

Components

Core Stack

• PHP 8.5 FPM - Main application runtime.
• Symfony 7 - High-performance PHP framework for the REST API.
• Nginx 1.29 - Web server and reverse proxy.

Data & Caching

• MySQL 8 - Primary relational database.
• Redis 8 - In-memory data structure store and cache.

Search & Asynchronous Processing

• Elasticsearch 7 - Distributed search and analytics engine.
• RabbitMQ 4 - Robust message broker for background jobs.

Monitoring & Development Tools

• Kibana 7 - Data visualization dashboard for Elasticsearch.
• Mailpit - Email testing tool (available in the development environment only).

Setting up Docker Engine & Docker Compose

To install Docker Engine and Docker Compose, please follow the official Docker Engine Installation Guide.

For Linux Users: After installation, run the following command to manage Docker as a non-root user (this allows you to run Docker without sudo):

sudo usermod -aG docker $USER

Note: You must log out and log back in for this change to take effect.

For macOS Users: If you are using Docker Desktop for macOS 12.2 or later, we highly recommend enabling virtiofs for a significant performance boost.

Note: Enabled by default since Docker Desktop v4.22.

Setting up the DEV environment

1. You can clone this repository from GitHub or install via composer.

   If you have installed composer and want to install environment via composer you can use next cmd command:

   composer create-project systemsdk/docker-symfony-api api-example-app

2. Set a unique APP_SECRET for the application in .env.prod and .env.staging files.

   • Secret Key: You can generate a secure key by running: openssl rand -hex 16 (do not use third-party websites for generating this value).
   • Environment Files: Do not use .env.local.php on dev and test environments (delete it if it exists).
   • Custom Configs: If you want to change default web port/xdebug configurations, you can create an .env.local file and override parameters there (see .env file).
   • Database: Delete the var/mysql-data folder if it exists before starting.

3. Verify that your local hosts file contains the default mapping for localhost (this is usually set by default in all operating systems):

   127.0.0.1    localhost
   

   Note: The file is located at /etc/hosts on Linux/macOS and C:\Windows\System32\drivers\etc\hosts on Windows.

4. Configure Xdebug (Optional)

   Depending on your operating system, you can customize Xdebug behavior by editing either /docker/dev/xdebug-main.ini (Linux/Windows) or /docker/dev/xdebug-osx.ini (macOS).

   • To debug every request (Default):

     This is the default setting. It will intercept and debug all incoming API requests.

     xdebug.start_with_request = yes

   • To debug only specific requests (On-Demand):

     If you prefer to trigger the debugger manually only when making requests from a browser frontend, change the configuration to:

     xdebug.start_with_request = no

     Tip: Install the "Xdebug helper" extension for Chrome or Firefox and set the IDE Key to PHPSTORM in the extension settings.

5. Elasticsearch & Kibana Credentials

   Elasticsearch is pre-configured with a privileged bootstrap user. You can use these credentials to log into the Kibana dashboard:

   • Username: elastic
   • Password: changeme

   Security Note: You must use a strong, unique password for staging and production environments. Never use these default credentials outside of local development.

6. Build and Initialize the Environment

   Run the following commands in your terminal to build the Docker images, start the containers, install PHP dependencies and generate the JWT authentication keys:

   make build
   make start
   make composer-install
   make generate-jwt-keys

7. Apply Migrations and Configurations

   Execute the following commands to set up the database structure, initialize default user roles and groups, configure cron jobs, prepare message broker transports and apply Elasticsearch templates:

   make migrate
   make create-roles-groups
   make migrate-cron-jobs
   make messenger-setup-transports
   make elastic-create-or-update-template

8. Access Application Services

   Once the environment is successfully running, you can access the various services in your browser using the following URLs:

   • API Documentation: http://localhost/api/doc
   • RabbitMQ Management: http://localhost:15672
   • Kibana Dashboard: http://localhost:5601 (Use the credentials from Step 6)
   • Mailpit (Debug Email): http://localhost:8025

Setting up the STAGING environment locally

Important: This section describes how to set up the staging environment locally for debugging and verification purposes only. A real STAGING environment must be deployed on a dedicated server and should be as close to the PRODUCTION environment as possible.

Note: These steps assume you have already completed steps 1 through 3 of the "Setting up the DEV environment" section above.

1. Database Clean-up

   Delete the var/mysql-data folder if it exists before starting.

2. Elasticsearch & Kibana Credentials

   Elasticsearch is pre-configured with a privileged bootstrap user. You can use these credentials to log into the Kibana dashboard:

   • Username: elastic
   • Password: changeme

   Security Note: You must use a strong, unique password for the real staging environment. Never use these default credentials outside of local development.

3. Build and Initialize the Environment

   Run the following commands in your terminal to build the staging Docker images, start the containers and generate the JWT authentication keys:

   make build-staging
   make start-staging
   make generate-jwt-keys

   Note: With opcache.validate_timestamps=0 (php.ini) enabled for performance, any manual file changes or code updates require a PHP-FPM restart/reload to take effect.

4. Apply Migrations and Configurations

   Execute the following commands to set up the database structure, initialize default user roles and groups, configure cron jobs, prepare message broker transports and apply Elasticsearch templates:

   make migrate-no-test
   make create-roles-groups
   make migrate-cron-jobs
   make messenger-setup-transports
   make elastic-create-or-update-template

Setting up the PROD environment locally

Important: This section describes how to set up the production environment locally for debugging and verification purposes only. A real PROD environment must be deployed on a dedicated server.

Note: These steps assume you have already completed steps 1 through 3 of the "Setting up the DEV environment" section above.

1. Database and RabbitMQ Clean-up

   Delete the var/mysql-data, var/rabbitmq and var/elasticsearch-data/nodes folders if they exist before starting.

2. Edit the .env.prod file and set a secure password for MySQL, as well as a username and password for RabbitMQ.

3. Elasticsearch & Kibana Credentials

   Elasticsearch is pre-configured with a privileged bootstrap user. You can use these credentials to log into the Kibana dashboard:

   • Username: elastic
   • Password: changeme

   Security Note: You must use a strong, unique password for the real production environment. Never use these default credentials outside of local development.

4. Build and Initialize the Environment

   Run the following commands in your terminal to build the production Docker images, start the containers and generate the JWT authentication keys:

   make build-prod
   make start-prod
   make generate-jwt-keys

   Note: With opcache.validate_timestamps=0 (php.ini) enabled for performance, any manual file changes or code updates require a PHP-FPM restart/reload to take effect.

5. Apply Migrations and Configurations

   Execute the following commands to set up the database structure, initialize default user roles and groups, configure cron jobs, prepare message broker transports and apply Elasticsearch templates:

   make migrate-no-test
   make create-roles-groups
   make migrate-cron-jobs
   make messenger-setup-transports
   make elastic-create-or-update-template

Enabling Paid Features for Elasticsearch

To unlock Elasticsearch's paid features (for a 30-day trial), you need to modify its configuration file:

1. Open /docker/elasticsearch/config/elasticsearch.yml.
2. Change the value of the xpack.license.self_generated.type option from basic to trial.
3. Restart the environment to apply the changes.

Accessing Container Shells

Once the application is running (via make start), you can easily access the command line inside your containers.

To open a shell inside the main Symfony container, run:

make ssh

You can also access the other services using the following commands:

make ssh-nginx
make ssh-supervisord
make ssh-mysql
make ssh-rabbitmq

Tip: Type exit and press Enter to leave the container's shell and return to your local terminal.

Rebuilding Containers

If you modify any Dockerfile or environment configurations, you will need to rebuild the containers using the following commands:

make down
make build
make start

Note: Use environment-specific commands if you need to rebuild the test, staging, or production environments. For a complete list of available commands, run make help.

Starting and Stopping Containers

Use the following commands to start or stop the development environment:

make start
make stop

If you are working with the staging or production environments, use their respective commands:

• Staging: make start-staging or make stop-staging.
• Production: make start-prod or make stop-prod.

Stopping and Removing Containers

To completely stop and remove all environment containers and networks, use the following command:

make down

Note: Use environment-specific commands if you need to tear down the test, staging, or production environments. For a complete list of available commands, run make help.

Available Makefile Commands

Here is a reference list of the primary commands available for managing the environment, databases, logs and testing:

make build
make build-test
make build-staging
make build-prod

make start
make start-test
make start-staging
make start-prod

make stop
make stop-test
make stop-staging
make stop-prod

make down
make down-test
make down-staging
make down-prod

make restart
make restart-test
make restart-staging
make restart-prod

make env-staging
make env-prod

make generate-jwt-keys

make ssh
make ssh-root
make fish
make ssh-nginx
make ssh-supervisord
make ssh-mysql
make ssh-rabbitmq
make ssh-elasticsearch
make ssh-kibana

make composer-install-no-dev
make composer-install
make composer-update
make composer-audit

make info
make help

make logs
make logs-nginx
make logs-supervisord
make logs-mysql
make logs-rabbitmq
make logs-elasticsearch
make logs-kibana
make logs-redis

make drop-migrate
make migrate
make migrate-no-test
make migrate-cron-jobs

make fixtures

make create-roles-groups

make messenger-setup-transports

make elastic-create-or-update-template

make phpunit
make report-code-coverage

make phpcs
make ecs
make ecs-fix
make phpmetrics
make phpcpd
make phpcpd-html-report
make phpmd
make phpstan
make phpinsights

# ... and many more

Note: For a complete list of all available commands, please inspect the Makefile directly or run make help.

Architecture & packages

Core Framework & Utilities

• Symfony
• messenger
• api-doc-bundle
• cors-bundle
• command-scheduler-bundle
• automapper-plus-bundle
• symfony-console-form
• easy-log-bundle
• device-detector

Database & Search

• doctrine-migrations-bundle
• doctrine-fixtures-bundle
• uuid-doctrine
• doctrine-extensions
• beberlei/doctrineextensions
• elasticsearch

Authentication & Security

• jwt-authentication-bundle
• security-checker
• security-advisories

Testing, QA & Static Analysis

• phpunit
• phpunit-bridge
• dama/doctrine-test-bundle
• browser-kit
• css-selector
• php-coveralls
• phpstan
• phpmd
• phpcpd
• PhpMetrics
• phpinsights
• easy-coding-standard (ECS)
• rector

Composer & Infrastructure Tools

• composer-bin-plugin
• composer-normalize
• composer-unused
• composer-require-checker
• requirements-checker

Guidelines

• Commands
• Development
• IDE PhpStorm Configuration
• Xdebug Configuration
• Swagger
• Postman
• Redis GUI
• Messenger Component
• Code Quality Tools
• Testing
• API Key

Development Workflow

1. Branching: Create a new branch from develop using one of the following patterns:
   • feature/{ticketNo}
   • bugfix/{ticketNo}
2. Commits: Commit frequently and write clear, descriptive commit messages to facilitate the review process.
3. Pull Request: Push your branch to the repository and open a Pull Request (PR) against the develop branch. Use the following naming convention for your PR: feature/{ticketNo} - Short descriptive title of the Jira task.
4. Review: Address any feedback from reviewers and iterate as needed.
5. CI/CD Checks: Ensure that all continuous integration checks (e.g., CircleCI) pass successfully and the build status is green.
6. Merge: Once approved, your PR will be squashed and merged into develop. It will later be merged into a release/{version} branch for deployment.

Note: For a detailed visual guide on this branching model, please refer to the Git Flow Cheatsheet.

License

The MIT License (MIT)