Development Guide for mailserver-admin

This document describes the development setup and workflow for the mailserver-admin project. The project is located in a separate repository: https://github.com/jeboehm/mailserver-admin/

Technical Stack

  • PHP
  • Symfony
  • EasyAdmin
  • MySQL
  • Redis
  • PHPUnit

Development Environment Setup

The project uses devenv to provide a reproducible development environment with all necessary services and dependencies.

Prerequisites

  • Nix installed on your system
  • devenv installed

Initial Setup

  1. Clone the repository:
git clone <repository-url>
cd mailserver-admin
  1. Start the development environment:
devenv up

This command will: - Set up PHP 8.4 with required extensions (Redis, PDO MySQL, Xdebug) - Start MySQL database server - Start Redis server - Start Caddy web server on port 8000 - Configure PHP-FPM pool for the web server - Set up environment variables for database and Redis connections

  1. Install dependencies: 
    composer install

Starting the Web Server

Important: You must run devenv up to start the web server. This command starts all required services including:

  • Caddy web server on http://localhost:8000
  • MySQL database (accessible at 127.0.0.1)
  • Redis server (accessible at localhost:6379)

The web server is configured to serve files from the public/ directory and uses PHP-FPM for PHP execution.

Development Commands

The project includes several composer scripts for development tasks:

Code Style Fixing

Fix code style issues using PHP CS Fixer:

composer run csfix

This command runs PHP CS Fixer with the configuration defined in .php-cs-fixer.dist.php. It applies PSR-2, Symfony, and PHP 8.0 migration rules to files in:

  • bin/
  • public/
  • tests/
  • src/
  • migrations/

Static Analysis

Run PHPStan to perform static analysis:

composer run phpstan

PHPStan is configured to analyze code at level 6 (as defined in phpstan.dist.neon) and checks:

  • bin/
  • config/
  • public/
  • src/
  • tests/

Running Tests

Execute the test suite:

composer run test

This runs PHPUnit with the configuration from phpunit.dist.xml. The test suite includes:

  • Unit tests in tests/Unit/
  • Integration tests in tests/Integration/

Tests run in the test environment and use the database configured in .env.test.

Test Coverage

Generate test coverage report:

composer run coverage

This runs PHPUnit with Xdebug coverage enabled and outputs a text-based coverage report.

Code Refactoring

Run Rector to automatically refactor code:

composer run rector

Rector uses the configuration from rector.php to apply automated code improvements and migrations.

Project Structure

  • src/: Application source code
  • tests/: Test files (Unit and Integration)
  • config/: Symfony configuration files
  • public/: Web server document root
  • migrations/: Database migration files
  • templates/: Twig templates
  • bin/: Executable scripts (console, phpunit)

Development Workflow

  1. Start the environment: devenv up
  2. Make your changes in the appropriate directories
  3. Fix code style: composer run csfix
  4. Check static analysis: composer run phpstan
  5. Run tests: composer run test
  6. Commit your changes following the project's commit message conventions

Debugging

Xdebug is configured in the devenv setup with:

  • Mode: debug
  • Client port: 9003
  • Start with request: enabled

Configure your IDE to connect to Xdebug on port 9003 for debugging.

Database Migrations

When making database schema changes:

  1. Create a migration:
php bin/console doctrine:migrations:generate

  1. Edit the generated migration file in migrations/

  2. Run migrations: 

    php bin/console doctrine:migrations:migrate

Additional Resources