A template for building structured, maintainable, and scalable REST APIs in Slim Framework applications, following ADR architecture and clear separation of concerns.
This template provides a foundation for building structured, maintainable, and scalable REST APIs in Slim Framework applications, following Action–Domain–Responder (ADR) architecture and clear separation of concerns. It includes a shutdown handler for consistent error responses, a dedicated CORS response emitter, structured logging via Monolog, and environment configuration through PHP dotenv. Working alongside Slim’s error middleware, these components ensure uniform behaviour, consistent error payloads, and seamless integration of cross-cutting concerns. The setup also includes modern tooling, testing, and optional containerisation, along with a complete feature example for reference or extension.
Before you begin, ensure you have met the following requirements:
- PHP: Version 8.3 or higher is required.
- Composer: Dependency management tool for PHP.
- Docker (optional): For running the application in a containerised environment.
This project follows an ADR-style architecture, organising code by responsibility:
- Application: HTTP layer and use-case coordination
- Domain: Core business logic and contracts
- Infrastructure: External integrations and implementations
The structure is intentionally simple and feature-oriented, allowing features to grow vertically without blurring boundaries between layers.
repo/
├── app/ # PSR-4 Autoloaded logic
│ ├── Application/ # Request handling & orchestration
│ ├── Domain/ # Business logic & interface contracts
│ ├── Infrastructure/ # External integrations & implementations
│ └── helpers.php # Global utility functions
│
├── bootstrap/ # Application configuration layer
│ ├── app.php # Application bootstrap & initialization
│ ├── dependencies.php # Container service registrations
│ ├── middleware.php # HTTP middleware pipeline configuration
│ ├── repositories.php # Interface → implementation bindings
│ ├── routes.php # Slim route definitions
│ └── settings.php # Configuration arrays
│
├── public/ # Web server document root
│ └── index.php # HTTP entry point
│
├── resources/ # Development & documentation assets
│ └── http/ # HTTP request/response examples
│
├── storage/ # File-based storage
│ └── logs/ # Monolog output
│
├── tests/ # PHPUnit Test Suite
│ ├── Integration/ # Full HTTP stack tests
│ └── Unit/ # Isolated logic tests
│
├── workbench/ # Scratchpad for local experimentation
│
├── composer.json # Project dependencies and scripts
├── Dockerfile # Container build instructions
├── phpunit.xml # PHPUnit configuration
└── .env.example # Example environment variables file
The template includes a simple Users feature to demonstrate how a vertical slice can be structured using the ADR approach. This example shows how a single feature can be organised across all layers:
- Actions: HTTP entry points for creating, retrieving, listing, updating, and deleting users.
- DTOs: Data transfer objects for input and output.
- Service: Application logic orchestrated in a dedicated service class.
- Domain: Entity and repository contracts define the business model and persistence interface.
- Infrastructure: In-memory repository implementation for demonstration purposes.
Routes are versioned under /api/v1 and follow RESTful conventions:
| Method | Path | Description |
|---|---|---|
GET |
/api/v1/users |
List all users |
POST |
/api/v1/users |
Create a user |
GET |
/api/v1/users/{id} |
Retrieve a user |
PUT |
/api/v1/users/{id} |
Update a user |
DELETE |
/api/v1/users/{id} |
Delete a user |
This feature is provided as a reference and starting point. It may be used as a template for additional features, or removed entirely when initialising a new project.
Application configuration and bootstrapping are organised inside the bootstrap/ directory. Each file is responsible for a specific part of the application setup.
- app.php: Creates and configures the Slim application instance, including environment loading, container setup, middleware registration, error handling, and route registration.
- settings.php: Defines application configuration values such as environment mappings, error handling behaviour, logging settings, and CORS configuration.
- dependencies.php: Registers services in the dependency injection container, including infrastructure services and shared application components.
- repositories.php: Maps domain interfaces to their concrete implementations, keeping the domain layer decoupled from infrastructure.
- middleware.php: Configures the HTTP middleware pipeline, including cross-cutting concerns applied to incoming requests.
- routes.php: Defines HTTP routes and maps them to application actions, typically grouped and versioned.
Key runtime packages are managed via Composer, including:
- Slim Framework (v4) for routing, middleware composition, and HTTP application flow.
- Slim PSR-7 for handling HTTP requests and responses via a PSR-7 implementation.
- PHP-DI for dependency injection and service container management.
- Monolog for structured application logging.
- CORS Response Emitter for CORS-aware response emission.
- JSON Error Handler for consistent JSON-formatted error responses.
- Shutdown Handler for consistent shutdown and fatal error handling.
- phpdotenv for loading environment-based configuration.
See composer.json for the full list.
Development tooling is included for a consistent and reliable workflow:
- PHPUnit for unit and integration testing.
- PHP CS Fixer for automated code style enforcement.
- Docker for containerised development and deployment environments.
- GitHub Actions CI (Continuous Integration) workflow that runs on pushes to main and pull requests, executing unit and integration tests.
These tools ensure code quality, reproducibility, and smooth collaboration.
If you like what you've seen so far and think this setup fits your needs, you can quickly get started by clicking the Use this template button at the top of the repository on GitHub.
Licensed under the MIT license and is free for private or commercial projects.