Skip to content
Latest posts
Does Your Test Suite Actually Test Anything?
2026-03-24
MVC vs Clean Architecture: Where Your Code Actually Goes
2026-03-17
Copy-Based Framework: Own Your Code
2026-03-10

Phexium Framework

Phexium is a PHP clean architecture framework that combines hexagonal architecture, CQRS, and domain-driven design into a cohesive, opinionated structure. It targets complex, long-lived enterprise applications where maintainability outweighs time-to-market. Unlike traditional frameworks installed via Composer, Phexium uses a copy-based distribution model: the framework source code lives in your project's src/ directory, giving you full ownership and transparency over every component.

A Framework You Own

Most PHP frameworks hide their implementation behind vendor/, a read-only directory managed by Composer. Phexium takes the opposite approach with copy-based distribution: the complete framework source code becomes part of your project. You can read, modify, and extend any framework file without maintaining a separate fork, and you control when and what to update via standard Git workflows.

Aspect Traditional Frameworks Phexium
Location vendor/ (read-only) src/ (your code)
Ownership External dependency Part of your project
Updates Composer forces version You choose when and what

For a detailed explanation of this distribution model, see Copy-Based Framework.

Architecture-First Design

Phexium does not treat architectural patterns as optional add-ons. Clean Architecture, CQRS, and DDD are the foundation, and layer boundaries are enforced by Deptrac static analysis.

Clean Architecture organizes code into four layers (Domain, Application, Infrastructure, and Presentation) with a strict inward dependency rule. Inner layers never depend on outer layers, keeping business logic isolated from technical concerns.

CQRS separates write operations (Commands) from read operations (Queries), each dispatched through dedicated buses with their own handlers and middleware. This separation simplifies reasoning about data flow and enables independent optimization of reads and writes.

Hexagonal Architecture materializes through the plugin system, where each of the built-in plugins pairs a Port (interface) with one or more Adapters (implementations). Application code depends on Ports, making infrastructure swappable without touching business logic.

Domain-Driven Design provides the tactical building blocks: Entities with identity and behavior, immutable Value Objects for self-validating domain primitives, Aggregates defining consistency boundaries, and Domain Events capturing facts that happened in the business domain.

Who Phexium Is For

Phexium serves a specific audience where architectural rigor justifies the additional structure:

  • Teams building applications in complex business domains (insurance, finance, logistics) where domain logic drives the architecture, not CRUD operations.
  • Organizations developing long-lived enterprise applications that multiple developers will maintain over years, and where preventing codebase degradation matters.
  • Developers and teams learning Clean Architecture, CQRS, and DDD in practice, using the framework as a reference implementation and educational tool.
  • Teams recovering from poorly structured legacy codebases, looking for an opinionated structure that enforces boundaries from day one.

Phexium is probably not the right choice for MVPs, prototypes, or simple CRUD applications where development speed matters most. For a detailed comparison with other frameworks and a decision guide, see When to Use Phexium.

Key Features

Dual-Mode Architecture: Bus Mode (CQRS with CommandBus, QueryBus, and middleware) handles complex business logic, while Direct Mode (UseCase pattern) serves simpler operations. Both modes coexist in the same application, allowing each feature to use the appropriate level of structure.

Plugin System: Self-contained Port & Adapter plugins cover cross-cutting concerns: from command and event buses to caching, logging, session management, and password hashing. Each plugin defines a clean interface and ships with multiple adapter implementations.

Multiple Database Support: Every repository provides InMemory, SQLite, MySQL, and PostgreSQL adapters. InMemory adapters enable fast, isolated unit tests without any database setup, while production adapters share the same interface contract.

Event-Driven Architecture: The EventBus plugin enables publish/subscribe domain events, allowing modules to react to changes in other aggregates without direct coupling. Event listeners are registered declaratively and execute after command completion.

Documentation

Quick Start

git clone https://gitlab.com/phexium/framework.git
cd phexium
task composer:install
task dev:environment:start

Access the demo application at http://localhost:8080.

See Installation for complete setup instructions.