foundation/README.md

# Foundation - PHP Framework

A small PHP framework built with Domain-Driven Design principles, Slim microframework, and dependency injection.

## Features

- **Clean Architecture**: Separation of concerns with Domain, Application, and Infrastructure layers
- **Domain-Driven Design**: Proper domain modeling with entities, value objects, and repositories
- **Dependency Injection**: PHP-DI container for flexible service management
- **Modular System**: Self-contained modules with auto-discovery service providers
- **HTTP Framework**: Slim 4 for robust request handling
- **Attribute-Based Routing**: PHP 8+ attributes for clean route definitions
- **Database Layer**: PDO with repository pattern and CQRS separation
- **Docker Support**: Complete development environment with PHP, MySQL, and Xdebug

## Quick Start

### Docker Development Environment (Recommended)

1. **Prerequisites**: Docker and Docker Compose installed

1. **Setup**:
   ```bash
   git clone git@github.com:ItsAMirko/foundation.git foundation
   cd foundation
   
   # Start development environment (recommended)
   make up
   make install
   
   # Alternative: automated setup script
   ./docker-start.sh
   ```

1. **Access Application**:
    - **Web Interface**: http://localhost:8000
    - **phpMyAdmin**: http://localhost:8080

### Local Development

1. **Requirements**: PHP 8.1+, MySQL 8.0+, Composer

1. **Setup**:
   ```bash
   composer install
   cp .env.example .env
   # Configure database settings in .env
   mysql < database/schema.sql
   ```

1. **Run**:
   ```bash
   php -S localhost:8000 -t public/
   ```

## Architecture

### Core Framework Structure

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

### Module Structure (Example: WelcomeScreen)

```
src/Modules/WelcomeScreen/
├── Application/                          # Use cases and application services
│   ├── FetchAllActivities/
│   └── SetAllActivitiesAsRead/
├── Domain/                               # Business logic and domain models
│   ├── Activity.php                      # Domain entity
│   └── ActivityRepositoryInterface.php
├── Infrastructure/                       # External concerns
│   ├── Api/                              # API controllers
│   ├── Web/                              # Web controllers  
│   └── Database/                         # Database implementations
└── WelcomeScreenServiceProvider.php      # Module service registration
```

## Key Concepts

### Service Providers

Each module has a Service Provider that:

- Registers services in the DI container
- Bootstraps module-specific functionality
- Registers HTTP routes
- Can handle future event registration

### Bootstrappers

Framework components that set up the application:

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

### Domain-Driven Design

- **Entities**: Business objects with identity
- **Value Objects**: Immutable data containers
- **Repositories**: Data access abstractions
- **Application Services**: Use case implementations
- **Domain Services**: Business logic coordination

## Development

### Development Commands

Use the included Makefile for streamlined development:

```bash
# View all available commands
make help

# Environment management
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 only
make test-integration      # Run integration tests only
make test-coverage         # Run tests with coverage report

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

### Docker Environment

See [Docker Setup Documentation](documentation/docker-setup.md) for detailed Docker usage.

### Adding New Modules

1. Create module directory: `src/Modules/<module-name>/`
2. Implement Domain, Application, and Infrastructure layers
3. Create `<module-name>ServiceProvider.php`
4. The ModuleLoader will automatically discover and register it

### Debugging

With Docker and Xdebug configured:

- Set breakpoints in your IDE
- Access the application through http://localhost:8000
- Debug sessions will automatically connect

## Documentation

### Architecture & Design

- [Application Core](documentation/application-core.md) - Framework Architecture Overview
- [Application Layers](documentation/application-layers.md) - Application Layer Guide
- [Attribute-Based Routing](documentation/attribute-routing.md) - Modern PHP 8+ Routing with Attributes
- [Docker Setup](documentation/docker-setup.md) - Docker Setup Guide
- [Dependency Injection](documentation/dependency-injection.md) - Dependency Injection Guide
- [Unit of Work](documentation/unit-of-work.md) - Unit of Work Guide

## Requirements

- PHP 8.1+
- MySQL 8.0+ / MariaDB 10.3+
- Composer
- Docker & Docker Compose (for development environment)

## Dependencies

### Core Framework

- **slim/slim**: ^4.12 - HTTP microframework
- **php-di/php-di**: ^7.0 - Dependency injection container
- **monolog/monolog**: ^3.0 - Logging library
- **vlucas/phpdotenv**: ^5.5 - Environment configuration

### Development Tools

- **phpunit/phpunit**: ^10.0 - Testing framework
- **phpstan/phpstan**: ^1.10 - Static analysis