anvilm/slim-rr-boilerplate

Slim 4, RoadRunner boilerplate

v1.0.0 2025-10-24 19:18 UTC

Requires

• cycle/migrations: ^4.2
• cycle/orm: ^2.11
• monolog/monolog: ^3.9
• nyholm/psr7: ^1.8
• nyholm/psr7-server: ^1.1
• oscarotero/env: ^2.1
• php-di/php-di: ^7.1
• slim/slim: 4.*
• spiral/roadrunner-http: ^3.6
• symfony/console: ^7.3

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.4

MIT

• anvilm

README

Slim · RoadRunner Boilerplate

PHP Boilerplate Powered by Slim Framework and RoadRunner

Project Overview

This template is designed for the development of web applications utilizing the Slim Framework and the high-performance RoadRunner server. The project incorporates tools for building scalable PHP applications, including a dependency injection container, logging system, Object-Relational Mapping (ORM), database migrations, and a Command Line Interface (CLI).

Core Components

• Container: PHP-DI
• HTTP: nyholm/psr7
• Logger: Monolog
• ORM: CycleORM
• Migrations: Cycle Migrations
• CLI: Symfony Console
• Testing: PHPUnit
• Static Analysis: PHPStan

Getting Started

Installation

Via Composer

Create a new project using Composer:

composer create-project anvilm/slim-rr-boilerplate my-project

Via GitHub

Clone the repository and install dependencies:

git clone https://github.com/anvilm/slim-rr-boilerplate.git my-project
cd my-project
composer install

Directory Structure

.
├── app/                          # Core application logic and infrastructure
│   ├── Bootstrappers/            # Classes for initializing application components
│   ├── Commands/                 # Custom CLI commands
│   ├── Config/                   # Configuration files
│   ├── Endpoints/                # Definitions of HTTP endpoints
│   ├── Providers/                # Dependency injection container providers
│   │   ├── ApplicationProviders/ # Providers for application functionality
│   │   └── Providers/            # Custom providers
│   └── Kernel.php                # Application entry point and bootstrap management
├── bin/                          # CLI entry point
│   └── console.php               # Entry point for Symfony Console
├── database/                     # Migrations and SQLite database files
├── logs/                         # Application logs
├── src/                          # Source code for custom logic
├── tests/                        # PHPUnit tests
└── index.php                     # Entry point for RoadRunner

Directory Organization

The boilerplate is structured to separate infrastructural logic from user-defined code:

• Directory app/: Contains the core infrastructure of the application, including configurations, providers, endpoints, and bootstrappers. This directory is intended for foundational application setup and operation.
• Directory src/: Designated for user-defined source code, where developers can implement the primary business logic of the application.

Configuration

Application configurations are organized in the app/Config/ directory and provide type-safe access to settings via classes with static methods. For further details, refer to the Configuration section.

Environment Variables

Environment variables are managed using the oscarotero/env library. These variables are read directly from the system, not from a .env file, and are intended for use within configuration classes.

Predefined environment variables:

• APP_ENV: Defines the application environment (e.g., production, development), affecting logging levels.
• APP_DEBUG: Enables or disables debug mode, influencing the display of detailed error information in Slim.

Application Configuration

The ApplicationConfig class provides the following parameters:

• baseDir: The root directory of the project.
• appEnv: The application environment, determined by the APP_ENV variable. Available environments are listed in the ApplicationEnvironmentEnum enumeration. To add a new environment, update this enumeration and the ApplicationConfig class.
• appDebug: Debug mode, determined by the APP_DEBUG variable. Enables detailed error messages.

Database Configuration

The DatabaseConfig class defines settings for CycleORM. By default, it is configured for SQLite, but other database management systems (e.g., MySQL, PostgreSQL) are supported with appropriate configuration.

Logging Configuration

The LoggerConfig class configures logging parameters using Monolog. It includes the path to log files (in the logs/ directory) and the logging level, which depends on the appEnv value.

Migration Configuration

Database migration settings are defined for Cycle Migrations. Migrations are stored in the database/migrations/ directory and managed via CLI commands.

Architectural Concepts

Configuration

Configurations are stored in the app/Config/ directory. Each configuration is implemented as a class with static methods, ensuring type-safe access to settings.

Example:

namespace Application\Config\ApplicationConfig;

use function Env\env;

final readonly class ApplicationConfig
{
    public static function baseDir(): string
    {
        return dirname(__DIR__, 3);
    }
}

Endpoints

HTTP endpoints are defined in the app/Endpoints/ directory. Routing is handled using the standard Slim Framework mechanism. Each endpoint class must implement the EndpointInterface and be registered in the EndpointBootstrapper.

Example of creating an endpoint:

namespace App\Endpoints;

final readonly class ApiEndpoints implements EndpointInterface
{
    public static function register(App $app): void
    {
        $app->get('/', function (RequestInterface $request, ResponseInterface $response) {
            $response->getBody()->write('Example response');
            return $response;
        });
    }
}

Example of registration in EndpointBootstrapper:

private static array $endpoints = [
    \App\Endpoints\ApiEndpoints::class,
];

Providers

Service providers, located in the app/Providers/ directory, are responsible for registering dependencies in the PHP-DI container, making them accessible to the application. Providers are categorized as follows:

• ApplicationProviders/: Providers essential for application functionality.
• Providers/: Custom providers for specific logic.

Each provider must implement the ProviderInterface and be registered in the ProvidersBootstrapper.

Example of creating a provider:

namespace App\Providers;

final readonly class DBALProvider implements ProviderInterface
{
    public static function register(): array
    {
        return [DatabaseManager::class => new DatabaseManager(
            new CycleDatabaseConfig(
                DatabaseConfig::config()
            )
        )];
    }
}

Example of registration in ProvidersBootstrapper:

private static array $appProviders = [
    \App\Providers\LoggerProvider::class,
    \App\Providers\DBALProvider::class,
];

private static array $providers = [
    // Custom providers
];

Bootstrappers

Bootstrapper classes in the app/Bootstrappers/ directory initialize key application components. The primary bootstrappers are:

• ApplicationBootstrapper: Initializes the Slim application.
• ContainerBootstrapper: Configures the PHP-DI container.
• ProvidersBootstrapper: Registers providers.
• EndpointBootstrapper: Registers endpoints.
• CommandsBootstrapper: Registers CLI commands.

The Kernel.php file manages the initialization process.

Commands

CLI commands are defined in the app/Commands/ directory. Each command must be registered in the CommandsBootstrapper.

The Symfony Console library is used for CLI commands.

Example of registration in CommandsBootstrapper:

private static array $commands = [
    \App\Commands\MigrationGenerateCommand::class,
    \App\Commands\MigrationUpCommand::class,
];

Available commands:

• migration:generate: Generates a migration template in the database/migrations/ directory.
• migration:up: Executes pending migrations.

Running commands:

php bin/console {commandName}

License

The project is distributed under the MIT License. For details, refer to the LICENSE file.