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

2. Setup:

   git clone git@github.com:ItsAMirko/foundation.git foundation
   cd foundation
   
   # Start development environment (recommended)
   make up
   make install
   

3. Access Application:

   • Web Interface: http://localhost:8000
   • phpMyAdmin: http://localhost:8080

Local Development

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

2. Setup:

   composer install
   cp .env.example .env
   # Configure database settings in .env
   mysql < database/schema.sql
   

3. Run:

   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:

# 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 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 - Framework Architecture Overview
• Application Layers - Application Layer Guide
• Attribute-Based Routing - Modern PHP 8+ Routing with Attributes
• Docker Setup - Docker Setup Guide
• Dependency Injection - Dependency Injection Guide
• Unit of Work - 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