michaelschiemer/.junie/guidelines.md

Project Guidelines

This document provides essential information for developers working on the michaelschiemer.de website project.

Build and Configuration Instructions

Environment Setup

The project uses Docker for local development. Make sure you have Docker and Docker Compose installed on your system.

Building the Project

1. Clone the repository
2. Create a .env file based on .env.example (if available)
3. Build the Docker containers:

./build.sh

The build script includes several resilience mechanisms:

• Checks network connectivity before attempting to pull images
• Flushes DNS cache to avoid DNS resolution issues
• Restarts the Docker daemon if it's not responding
• Multiple build strategies with fallbacks if the primary strategy fails

Starting the Development Environment

Start the Docker containers:

docker-compose up -d

This will start the following services:

• web: Nginx web server (ports 8000, 8080, 443)
• php: PHP application container
• db: MariaDB database (port 33060)
• redis: Redis cache server
• queue-worker: Worker container for processing queued jobs

Required PHP Extensions

The project requires the following PHP extensions:

• dom
• libxml
• curl
• pcntl
• fileinfo
• zlib
• gd
• pdo
• apcu
• redis
• zend-opcache
• openssl

Testing Information

Testing Framework

The project uses Pest PHP for testing, which is a testing framework built on top of PHPUnit with a more expressive syntax.

Running Tests

Run all tests:

./vendor/bin/pest

Run a specific test file:

./vendor/bin/pest tests/path/to/TestFile.php

Run tests with coverage report (requires Xdebug):

XDEBUG_MODE=coverage ./vendor/bin/pest --coverage

Writing Tests

Tests are located in the tests directory, with a structure that mirrors the application code. For example, tests for src/Framework/Random are in tests/Framework/Random.

Test files should:

• Be named with the suffix Test.php
• Use the appropriate namespace (e.g., Tests\Framework\Random for src/Framework/Random)
• Follow the Pest PHP testing style

Example Test

Here's an example test for the TestableRandomGenerator class:

<?php

declare(strict_types=1);

namespace Tests\Framework\Random;

use App\Framework\Random\TestableRandomGenerator;

test('erzeugt deterministische Bytes mit vorgegebener Länge', function () {
    $generator = new TestableRandomGenerator('test-seed');
    
    // Erste Ausführung
    $bytes1 = $generator->bytes(10);
    expect(strlen($bytes1))->toBe(10);
    
    // Generator zurücksetzen
    $generator->reset();
    
    // Zweite Ausführung nach Reset sollte identische Bytes erzeugen
    $bytes2 = $generator->bytes(10);
    expect($bytes2)->toBe($bytes1);
});

Note that test names are written in German, with descriptive names that explain what the test is checking.

Deployment

The project includes a deployment script (deploy.sh) that deploys the application to a remote server. The deployment process:

1. Creates a temporary directory
2. Copies project files to the temporary directory (excluding .git, node_modules, vendor, .env)
3. Creates an archive of the project
4. Creates directories on the remote server
5. Transfers the archive to the remote server
6. Extracts the archive on the remote server
7. Creates an .env file if it doesn't exist
8. Sets permissions for storage and cache directories
9. Installs dependencies and builds assets
10. Restarts Docker containers
11. Cleans up temporary files

To deploy the project:

./deploy.sh

Code Style and Quality

Code Style

The project uses PHP CS Fixer for code style checking and fixing. The configuration is defined in .php-cs-fixer.dist.php (or similar).

Run code style check:

composer cs

Fix code style issues:

composer cs-fix

Static Analysis

The project uses PHPStan for static analysis. The configuration is defined in phpstan.neon.

Run static analysis:

composer phpstan

Generate a baseline for static analysis:

composer phpstan-baseline

Project Structure

The project follows a domain-driven design approach with the following main directories:

• src/Application: Contains application-specific code
• src/Domain: Contains domain models and business logic
• src/Framework: Contains framework-level code
• src/Infrastructure: Contains infrastructure-level code

The Framework directory contains various components, including:

• Analytics: Analytics functionality
• Cache: Caching functionality
• Console: Console commands
• Database: Database functionality
• Http: HTTP functionality
• Random: Random number generation
• Security: Security functionality
• Validation: Validation functionality
• View: View rendering
• Waf: Web Application Firewall functionality

Additional Development Information

Composer Scripts

The project defines several Composer scripts for common tasks:

• composer cs: Run PHP CS Fixer in dry-run mode
• composer cs-fix: Run PHP CS Fixer to fix issues
• composer reload: Dump the autoloader optimized
• composer phpstan: Run PHPStan analysis
• composer phpstan-baseline: Generate a PHPStan baseline

Docker Networks

The Docker services are organized into three networks:

• frontend: For services that need to be accessible from outside
• backend: For services that need to communicate with each other
• cache: For services that need to access the cache

Docker Volumes

The Docker setup includes several volumes for persistent data:

• redis_data: Redis data
• composer-cache: Composer cache
• storage-data: Storage data
• var-data: Var data
• db_data: Database data
• project-data: Project data
• worker-logs: Worker logs
• worker-queue: Worker queue