PHPackages                             methorz/mezzio-hexagonal-skeleton - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. methorz/mezzio-hexagonal-skeleton

ActiveProject[API Development](/categories/api)

methorz/mezzio-hexagonal-skeleton
=================================

Mezzio skeleton with architecture choice: minimal or hexagonal (DDD). Includes optional packages for modern PHP 8.4+ REST API development.

v2.0.0(4mo ago)110MITPHPPHP ^8.4

Since Dec 30Pushed 3mo ago1 watchersCompare

[ Source](https://github.com/MethorZ/mezzio-hexagonal-skeleton)[ Packagist](https://packagist.org/packages/methorz/mezzio-hexagonal-skeleton)[ RSS](/packages/methorz-mezzio-hexagonal-skeleton/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (12)Versions (8)Used By (0)

Mezzio Skeleton with Architecture Choice
========================================

[](#mezzio-skeleton-with-architecture-choice)

> Mezzio skeleton with architecture choice: **Minimal** or **Hexagonal (DDD)**. Modern PHP 8.4+ development with optional packages.

[![PHP Version](https://camo.githubusercontent.com/504ead6a583c68d8d62d7bfceed24e569ca613d7a36bed380281b3455b5c7b31/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e342d626c7565)](https://www.php.net/)[![Mezzio](https://camo.githubusercontent.com/7634421eb7d21ae4c0af4a2338538feb59dfa7fe7e8280128e802b24dad0d5e8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6d657a7a696f2d253545332e32352d707572706c65)](https://docs.mezzio.dev/)[![Docker](https://camo.githubusercontent.com/907dfec9c19409ae0b8843ec169e3a954fabf9fc68c9c443d92b4348c38cabf3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f636b65722d72656164792d627269676874677265656e)](https://www.docker.com/)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE.md)

Overview
--------

[](#overview)

A modern Mezzio skeleton that lets you **choose your architecture** during setup:

- **PHP 8.4** with strict types
- **Mezzio Framework** for PSR-15 middleware
- **Laminas ServiceManager** for dependency injection
- **FastRoute** for high-performance routing
- **Docker** ready with PHP 8.4 + Nginx
- **Quality tools**: PHPStan (level 9), PHP\_CodeSniffer, PHPUnit
- **Architecture choice**: Minimal or Hexagonal (DDD)

Architecture Options
--------------------

[](#architecture-options)

During the interactive setup, you'll choose between two architectural approaches:

### 🏗️ Minimal Architecture

[](#️-minimal-architecture)

**Best for**: Small to medium projects, APIs, microservices, rapid prototyping

- Simple, flat structure
- Request handlers in `Application/Handler/`
- Straightforward and easy to understand
- Quick to get started

### 🎯 Hexagonal Architecture (Ports & Adapters / DDD)

[](#-hexagonal-architecture-ports--adapters--ddd)

**Best for**: Complex domains, large teams, long-term maintainability

- Domain-Driven Design with clear layer separation
- Business logic independent of framework
- Modular structure (Core, HealthCheck, Article example modules)
- Ports & Adapters pattern
- Comprehensive ARCHITECTURE.md guide included

**After setup**, your project will have an architecture-specific README with detailed guidance for your chosen approach.

Prerequisites
-------------

[](#prerequisites)

- Docker and Docker Compose

Getting Started
---------------

[](#getting-started)

### With Composer (One Command)

[](#with-composer-one-command)

```
composer create-project methorz/mezzio-hexagonal-skeleton my-project
```

> **Note:** If you have PHP < 8.4 on your host machine, use:
>
> ```
> composer create-project methorz/mezzio-hexagonal-skeleton my-project --ignore-platform-reqs
> ```
>
>
>
> This is safe because everything runs in Docker with PHP 8.4.

That's it! The setup will automatically:

- Run the interactive package installer
- Install all dependencies via Docker
- Build and start containers
- Launch your application at ****

**No PHP required on your host machine** - everything runs in Docker!

### Without Composer (Two Commands)

[](#without-composer-two-commands)

```
git clone https://github.com/MethorZ/mezzio-hexagonal-skeleton.git my-project
cd my-project
./setup.sh
```

Same automated process runs from here. Visit **** when complete.

What Happens During Setup
-------------------------

[](#what-happens-during-setup)

The setup process is fully automated:

1. **Architecture selection** - Choose between Minimal or Hexagonal architecture
2. **Interactive package selection** - Choose which optional packages to install (Monolog, Validator, Database, etc.)
3. **Package configuration** - ConfigProviders and middleware automatically registered
4. **Dependency installation** - Selected packages installed via Docker
5. **Docker image building** - Custom PHP 8.4 + Nginx images built
6. **Container startup** - Application containers started
7. **Development mode** - Development environment configured
8. **Verification & cleanup** - Setup verified, then setup files automatically removed

After successful setup, the project is production-ready with no setup artifacts left behind.

### Daily Development

[](#daily-development)

```
make start         # Start containers
make stop          # Stop containers
make shell         # Access backend shell
make logs-f        # View logs
make cs-fix        # Run code style fixes
make quality       # Run all quality checks
```

**Application URL**:

### Troubleshooting

[](#troubleshooting)

If setup fails:

- Setup files are **kept** for debugging
- Check logs: `make logs` or `docker-compose logs`
- After fixing issues, retry: `./setup.sh`
- If setup succeeds on retry, files are cleaned up automatically

Optional Packages
-----------------

[](#optional-packages)

The skeleton includes an **interactive installer** that prompts for optional packages when you create a new project. The installer will:

- Ask which packages you want to install
- Update `composer.json` with your selections
- Copy relevant configuration files
- Remove itself from your new project

### Core Infrastructure

[](#core-infrastructure)

- **Monolog** - Application logging
- **Symfony Validator** - Request validation with attributes
- **Symfony Cache** - Redis, APCu, filesystem caching
- **Symfony Console** - CLI command support

### MethorZ Packages

[](#methorz-packages)

- **methorz/http-dto** - Auto-map JSON requests to typed PHP objects
- **methorz/http-problem-details** - RFC 7807 JSON error responses
- **methorz/http-request-logger** - HTTP request/response logging middleware
- **methorz/http-cache-middleware** - HTTP caching with ETag/304
- **methorz/openapi-generator** - Auto-generate OpenAPI/Swagger docs

### Database Layer

[](#database-layer)

- **methorz/swift-db** - High-performance MySQL layer with Laravel-style query builder
    - Bulk operations, master/slave support, query builder
    - See:

### Adding Packages Later

[](#adding-packages-later)

To add packages after initial setup:

```
# From project root
make shell
# Inside container:
composer require methorz/swift-db
```

Project Structure
-----------------

[](#project-structure)

The project structure depends on your architecture choice:

- **Minimal**: Simple `backend/src/App/Application/` structure
- **Hexagonal**: Modular structure with `Core/`, `HealthCheck/`, `Article/` modules

**Example (Minimal Architecture)**:

```
project/
├── backend/
│   ├── src/
│   │   └── App/                    # Application module
│   │       └── Application/
│   │           ├── Config/         # ConfigProvider
│   │           └── Handler/        # HTTP handlers
│   ├── config/                     # Configuration files
│   ├── public/                     # Web root
│   ├── composer.json
│   ├── phpstan.neon
│   ├── phpcs.xml.dist
│   └── phpunit.xml.dist
├── docker/                         # Docker configuration
├── docker-compose.yml
├── Makefile
└── README.md

```

See your architecture-specific README after project creation for detailed structure documentation.

Command Reference
-----------------

[](#command-reference)

All commands run inside Docker containers - no PHP required on your host machine!

```
make help          # Show all available commands
make start         # Start development environment
make stop          # Stop containers
make restart       # Restart containers
make shell         # Access backend shell (inside container)
make logs          # View container logs
make logs-f        # Follow container logs
make cs-check      # Check code style (PSR-12)
make cs-fix        # Auto-fix code style issues
make analyze       # Run PHPStan (level 9)
make phpunit       # Run PHPUnit tests
make quality       # Run all quality checks (style + analysis + tests)
```

Adding Your Code
----------------

[](#adding-your-code)

1. Add handlers to `backend/src/App/Application/Handler/`
2. Register routes in `backend/src/App/Application/Config/ConfigProvider.php`
3. Add services and factories as needed

Example handler:

```