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:

```bash
./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:

```bash
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](https://pestphp.com/) for testing, which is a testing framework built on top of PHPUnit with a more expressive syntax.

### Running Tests

Run all tests:

```bash
./vendor/bin/pest
```

Run a specific test file:

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

Run tests with coverage report (requires Xdebug):

```bash
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
<?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:

```bash
./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:

```bash
composer cs
```

Fix code style issues:

```bash
composer cs-fix
```

### Static Analysis

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

Run static analysis:

```bash
composer phpstan
```

Generate a baseline for static analysis:

```bash
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