foundation/Claude.md

Foundation Framework - Claude Context

Project Overview

Foundation is a PHP framework built with Domain-Driven Design (DDD) principles, featuring clean architecture, modular design, and modern PHP 8+ capabilities. The framework emphasizes separation of concerns, testability, and maintainability.

Technology Stack

• PHP: 8.1+
• HTTP Framework: Slim 4
• Dependency Injection: PHP-DI 7.0
• Database: MySQL 8.0 with PDO and Repository pattern
• Logging: Monolog 3.0
• Environment Config: phpdotenv
• Development: Docker + Docker Compose with Xdebug

Architecture Principles

Clean Architecture Layers

The framework follows strict layered architecture with clear dependency rules:

Domain (Pure business logic - No dependencies)
   ↑
Application (Use cases - Depends on Domain only)
   ↑
Infrastructure (External adapters - Depends on Application only)

Layer Dependency Rules:

• Domain Layer: Completely independent, no external dependencies
• Application Layer: Can depend on Domain and itself only
• Infrastructure Layer: Can depend on Application and itself only

Module Structure

Each module follows this structure:

src/Modules/{ModuleName}/
├── Domain/                           # Pure business logic
│   ├── {Entity}.php                  # Entities with identity
│   ├── {ValueObject}.php             # Immutable value objects
│   └── {Repository}Interface.php     # Repository contracts
├── Application/                      # Use cases and orchestration
│   └── {UseCase}/
│       └── {UseCase}.php
└── Infrastructure/                   # External implementations
    ├── Api/                          # API controllers
    ├── Web/                          # Web controllers
    └── Database/                     # Repository implementations
        ├── {Repository}.php
        ├── Commands/
        └── Queries/

Core Framework Structure

src/Core/
├── Application/                      # Application orchestration
│   ├── Application.php               # Main application class
│   ├── Kernel/HttpKernel.php         # HTTP request handling
│   ├── DependencyInjection/          # DI container setup
│   ├── Bootstrapper/                 # Application initialization
│   └── ServiceProvider/              # Service registration abstractions
├── ErrorHandling/                    # Error handling and responses
├── Logging/                          # Logging infrastructure
├── Session/                          # Session management
└── Cache/                            # Caching interfaces

Key Concepts

1. Service Providers

Service Providers register services and bootstrap module-specific functionality:

• Register services in the DI container
• Bootstrap module-specific functionality
• Register HTTP routes via attribute scanning
• Auto-discovered by ModuleLoader from src/Modules/*/ directories

2. Bootstrappers

Framework components that set up the application before handling requests:

• ConfigInitializer - Environment configuration
• DatabaseInitializer - Database connections
• SessionInitializer - Session management
• ModuleLoader - Auto-discovers and loads module service providers

3. Dependency Injection Container

The framework uses InflectableContainer, a wrapper around PHP-DI with enhanced features:

• Container Inflection: Automatic method invocation during object resolution
• Smart Parameter Resolution: Intelligent detection of class names vs static values
• Simplified Registration: Clean syntax for dependency declaration

Example:

// Basic registration
$container->register(ServiceClass::class, [DependencyClass::class]);

// Interface binding
$container->bind(InterfaceClass::class, ImplementationClass::class, [Dep1::class]);

// Container inflection (automatic method calls)
$container->inflect(UnitOfWork::class)
          ->invokeMethod('registerPersister', [ActivityPersister::class]);

4. Attribute-Based Routing

Controllers use PHP 8+ attributes for route definitions:

• Controllers must implement ControllerInterface
• Routes automatically discovered during controller registration
• Available attributes: #[Get], #[Post], #[Put], #[Delete], #[Route], #[Group]

Example:

#[Group('/api/v1/users')]
class UserController implements ControllerInterface
{
    #[Get('')]
    public function index(): ResponseInterface { }

    #[Get('/{id}')]
    public function show(string $id): ResponseInterface { }

    #[Post('', middleware: [AuthMiddleware::class])]
    public function create(): ResponseInterface { }
}

5. Unit of Work Pattern

Manages database transactions and entity persistence:

• Entity Persisters: Handle database operations for specific entity types
• Registration: Via container inflection
• Transactional: All operations executed in single transaction

6. CQRS Separation

Commands (write operations) and Queries (read operations) are separated:

• Commands in Infrastructure/Database/Commands/
• Queries in Infrastructure/Database/Queries/

Development Workflow

Docker Environment

All development happens in Docker containers:

# Start environment
make up

# Install dependencies
make install

# Access container shell
make shell

Available Services:

• App: PHP 8.1 + Apache (http://localhost:8000)
• Database: MySQL 8.0 (port 3306)
• phpMyAdmin: Database management (http://localhost:8080)

Testing

Comprehensive testing suite with PHPUnit:

make test              # Run all tests
make test-unit         # Unit tests only
make test-integration  # Integration tests only
make test-coverage     # Coverage report

Code Quality

Static analysis and code quality tools:

make phpstan           # PHPStan static analysis
make deptrac           # Deptrac layer analysis
make static-analysis   # Run both
make rector            # Preview Rector changes
make rector-fix        # Apply Rector changes

Important Patterns

Adding New Modules

1. Create directory: src/Modules/{ModuleName}/
2. Implement Domain, Application, and Infrastructure layers
3. Create {ModuleName}ServiceProvider.php in module root
4. ModuleLoader automatically discovers and registers it

Creating Service Provider

class MyModuleServiceProvider extends ServiceProvider
{
    public function register(InflectableContainer $container): void
    {
        // Register services
        $container->register(MyController::class, [MyService::class]);

        // Bind interfaces
        $container->bind(MyRepositoryInterface::class, MyRepository::class);
    }
}

Repository Implementation

Repositories use Commands/Queries pattern:

class MyRepository implements MyRepositoryInterface
{
    public function __construct(
        private FetchAllQuery $fetchAll,
        private SaveCommand $save,
        private UnitOfWorkInterface $unitOfWork
    ) {}

    public function save(Entity $entity): void
    {
        $this->unitOfWork->registerNew($entity);
        $this->unitOfWork->commit();
    }
}

Authentication System

Two authentication modes available:

• Session-based: Traditional session authentication
• JWT-based: Token-based authentication with firebase/php-jwt

Configured via AUTH_TYPE environment variable.

Internationalization

Multi-language support using Symfony Translation:

• Default locale configurable via environment
• YAML translation files
• Module-specific translations supported

Environment Variables

Key environment variables (see .env.example):

# Database
DB_HOST=db
DB_PORT=3306
DB_DATABASE=foundation
DB_USERNAME=foundation_user
DB_PASSWORD=foundation_password

# Authentication
AUTH_TYPE=session
JWT_SECRET=your-secret-key
JWT_ACCESS_TOKEN_TTL=900

# Locale
APP_LOCALE=en
APP_SUPPORTED_LOCALES=en,de,fr

Debugging

Xdebug is configured for debugging:

• Set breakpoints in IDE
• Access application via http://localhost:8000
• Debug sessions automatically connect on port 9003

Documentation

Complete documentation available in ./documentation/:

• application-core.md - Framework architecture overview
• application-layers.md - Layer dependency rules
• attribute-routing.md - Route attribute system
• dependency-injection.md - DI container guide
• docker-setup.md - Docker environment details
• unit-of-work.md - Unit of Work pattern
• authentication.md - Authentication implementation
• internationalization.md - i18n setup

Common Commands Reference

Docker:

make up              # Start Docker environment
make down            # Stop Docker environment
make shell           # Access container shell

Dependencies:

make install         # Install composer dependencies
make dump-autoload   # Refresh autoload files

Testing:

make test            # Run all tests
make test-unit       # Run unit tests
make test-coverage   # Generate coverage report

Quality:

make phpstan         # Static analysis
make deptrac         # Layer analysis
make rector          # Code quality preview

Database:

# Import schema
docker compose exec -T db mysql -u foundation_user -pfoundation_password foundation < database/schema.sql

# Access MySQL CLI
docker compose exec db mysql -u foundation_user -p foundation

# Export database
docker compose exec db mysqldump -u foundation_user -pfoundation_password foundation > backup.sql

Best Practices

1. Always respect layer boundaries - Domain must remain pure
2. Use value objects for primitive obsession
3. Keep controllers thin - Delegate to application services
4. Use repository interfaces in Domain layer
5. Implement CQRS - Separate read and write operations
6. Write tests - Unit tests for domain, integration for infrastructure
7. Use attributes for routes - Don't register routes manually
8. Follow PSR standards - PSR-4 autoloading, PSR-7 HTTP messages
9. Document public APIs - Clear docblocks for interfaces
10. Use type hints - Leverage PHP 8.1+ type system

Troubleshooting

Docker Issues

• Ensure Docker and Docker Compose are installed
• Check port conflicts (8000, 8080, 3306)
• Verify user permissions: export USER_ID=$(id -u) && export GROUP_ID=$(id -g)

Database Connection Issues

• Verify database container is running: docker compose ps
• Check environment variables in .env
• Ensure database schema is imported

Routing Issues

• Verify controller implements ControllerInterface
• Check route attributes syntax
• Ensure controller is registered in service provider

Autoloading Issues

• Run make dump-autoload after adding new classes
• Verify PSR-4 namespace matches directory structure