Skip to main content

Introduction

This template provides a structured foundation for building maintainable and scalable REST APIs with Slim Framework. It follows the Action–Domain–Responder (ADR) architecture, separating application logic, domain logic, and infrastructure concerns into clearly defined layers.

Alongside Slim's middleware pipeline, the template includes structured logging, consistent JSON error responses, graceful shutdown handling, environment-based configuration, and optional containerisation. Modern testing and development tooling are configured out of the box, together with a complete example feature demonstrating the project's architecture and conventions.

Prerequisites​

Before getting started, ensure the following requirements are met:

  • PHP version 8.3 or higher
  • Composer for dependency management
  • Docker (optional, for containerising the application)

Structure​

The 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 application code
│   ├── Application/             # Request handling & orchestration
│   ├── Domain/                  # Business logic & interface contracts
│   ├── Infrastructure/          # External integrations & implementations
│   └── helpers.php              # Global utility functions
│
├── bootstrap/                   # Application configuration
│   ├── app.php                  # Application bootstrap & initialisation
│   ├── dependencies.php         # Dependency injection registrations
│   ├── middleware.php           # HTTP middleware pipeline
│   ├── repositories.php         # Interface-to-implementation bindings
│   ├── routes.php               # Route definitions
│   └── settings.php             # Configuration values
│
├── public/
│   └── index.php                # HTTP entry point
│
├── resources/
│   └── http/                    # HTTP request examples
│
├── storage/
│   └── logs/                    # Application logs
│
├── tests/
│   ├── Integration/             # HTTP integration tests
│   └── Unit/                    # Unit tests
│
├── workbench/                   # Local experimentation
│
├── composer.json
├── Dockerfile
├── phpunit.xml
└── .env.example

The template includes a simple Users feature demonstrating how a complete vertical slice is organised across the application:

  • Actions for handling HTTP requests
  • DTOs for request and response data
  • Services for application orchestration
  • Domain entities and repository contracts
  • Infrastructure implementations for data persistence

Routes are versioned under /api/v1 and follow RESTful conventions:

MethodPathDescription
GET/api/v1/usersList all users
POST/api/v1/usersCreate 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

The Users feature is intended as a reference implementation and starting point. It may be extended with additional features or removed entirely when creating a new project.

Configuration​

Application bootstrapping is organised within the bootstrap/ directory, with each file responsible for a specific aspect of the application's configuration.

  • app.php – Creates and configures the Slim application, including environment loading, dependency injection, middleware registration, error handling, and route registration.
  • settings.php – Defines configuration values such as environments, logging, error handling, and CORS settings.
  • dependencies.php – Registers shared services and infrastructure components within the dependency injection container.
  • repositories.php – Maps domain interfaces to their concrete implementations.
  • middleware.php – Configures the HTTP middleware pipeline.
  • routes.php – Defines and groups versioned API routes.

Runtime Packages​

The template includes a carefully selected set of runtime packages:

Tooling​

Development tooling is configured to support 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
  • GitHub Actions for CI/CD, running unit and integration tests on pushes to main and pull requests