README

Version: 1.x | PHP: >=7.4 || >=8.2 | License: MIT

Overview

The Slim Module Middleware (magmasoftwareengineering/slim-module-middleware) provides a modular architecture for Slim 4 applications, enabling you to encapsulate features into self-contained, reusable modules. Each module is a standalone bundle of controllers, routes, views, and configuration that can be independently developed and maintained.

This library is a foundational tool for building scalable, plugin-based Slim 4 applications. It works alongside the Slim Base Library to provide both HTTP framework capabilities and module organization.

Key Features

Module System

• ModuleInterface - Contract for all modules in your application
• AbstractModule - Base class with automatic configuration discovery
• ModuleLoader - Dynamically loads and registers modules with the Slim application

Architecture Benefits

• Encapsulation - Each module is self-contained with its own controllers, services, and views
• Reusability - Modules can be shared across multiple applications
• Scalability - Grow applications by adding modules without modifying core code
• Plugin Architecture - Load/unload modules dynamically at runtime
• Nested Modules - Support for hierarchical module structures (up to 4 levels deep)

Configuration Management

• Dependencies - Per-module dependencies.php for DI configuration
• Middleware - Per-module middleware.php for request pipeline setup
• Routes - Per-module routes.php for endpoint definitions
• Settings - Per-module settings.php for module-specific config

Dependencies

php: >=7.4 || >=8.2
slim/slim: ^4.13                (HTTP framework)
slim/psr7: ^1.6                 (PSR-7 implementation)
psr/http-message: ^1.1 || ^2.0  (HTTP message interfaces)
psr/log: ^3.0                   (Logging interface)

Installation

Installation is only supported through Composer:

composer require magmasoftwareengineering/slim-module-middleware:^1.0

Also requires Slim 4:

composer require slim/slim:^4.15

Usage Examples

Creating a Module

A module is a self-contained directory with a Module.php file. The module loader automatically discovers the module's namespace and configuration:

<?php
// src/modules/User/Module.php
namespace MyApp\Modules\User;

use MagmaSoftwareEngineering\Slim\Module\AbstractModule;

class Module extends AbstractModule {
    // Automatically discovers:
    // - Namespace: MyApp\Modules\User
    // - Directory: src/modules/User/src
}

Module Directory Structure

You can organise modules flexibly, with support for nested structures (up to 4 levels deep):

src/
└── modules/
    ├── Admin/
    │   ├── Module.php
    │   ├── src/
    │   │   ├── Controller/
    │   │   │   └── AdminController.php
    │   │   ├── Service/
    │   │   │   └── AdminService.php
    │   │   └── dependencies.php
    │   ├── middleware.php
    │   ├── routes.php
    │   └── settings.php
    ├── User/
    │   ├── Module.php
    │   ├── src/
    │   │   ├── Controller/
    │   │   │   └── UserController.php
    │   │   ├── Service/
    │   │   │   └── UserService.php
    │   │   ├── Entity/
    │   │   │   └── User.php
    │   │   ├── Repository/
    │   │   │   └── UserRepository.php
    │   │   └── dependencies.php
    │   ├── middleware.php
    │   ├── routes.php
    │   └── settings.php
    └── Dashboard/
        ├── Admin/
        │   ├── Module.php
        │   ├── src/
        │   │   ├── Controller/
        │   │   │   └── AdminDashboardController.php
        │   │   └── dependencies.php
        │   └── routes.php
        └── User/
            ├── Module.php
            ├── src/
            │   ├── Controller/
            │   │   └── UserDashboardController.php
            │   └── dependencies.php
            └── routes.php

Module Configuration Files

Each module can include standard configuration files:

dependencies.php - Dependency Injection

<?php
// src/modules/User/dependencies.php
use DI\Container;
use MyApp\Modules\User\Service\UserService;
use MyApp\Modules\User\Repository\UserRepository;

return static function (Container $container): void {
    $container->set(UserRepository::class, function () use ($container) {
        return new UserRepository($container->get(\Doctrine\ORM\EntityManagerInterface::class));
    });

    $container->set(UserService::class, function () use ($container) {
        return new UserService($container->get(UserRepository::class));
    });
};

routes.php - Route Registration

<?php
// src/modules/User/routes.php
use Slim\Routing\RouteCollectorProxy;
use MyApp\Modules\User\Controller\UserController;

return static function (RouteCollectorProxy $group): void {
    $group->get('', [UserController::class, 'list'])->setName('users.list');
    $group->post('', [UserController::class, 'create'])->setName('users.create');
    $group->get('/{id}', [UserController::class, 'show'])->setName('users.show');
    $group->put('/{id}', [UserController::class, 'update'])->setName('users.update');
    $group->delete('/{id}', [UserController::class, 'delete'])->setName('users.delete');
};

middleware.php - Middleware Pipeline

<?php
// src/modules/User/middleware.php
use Slim\App;
use MyApp\Modules\User\Middleware\ValidateUserInput;

return static function (App $app): void {
    // Module-specific middleware
    $app->add(new ValidateUserInput());
};

settings.php - Module Configuration

<?php
// src/modules/User/settings.php
return [
    'user' => [
        'registration_enabled' => true,
        'email_verification_required' => false,
        'default_role' => 'user',
    ],
];

Bootstrap Configuration

Configure module loading in your application settings:

<?php
// config/settings.php
return [
    'settings' => [
        // ... other Slim settings ...

        'modules' => [
            'path' => [
                dirname(__DIR__) . '/src/modules',        // Application modules
                dirname(__DIR__) . '/vendor/magmasoftwareengineering',  // Library modules
            ],
            'middleware' => [
                'MagmaSoftwareEngineering\\PhpDebugBar',  // Middleware modules
            ],
            'load' => [
                'MagmaSoftwareEngineering\\Rollout',      // Feature flagging
                'MyApp\\Modules\\User',                    // Application modules
                'MyApp\\Modules\\Admin',
                'MyApp\\Modules\\Dashboard',
            ],
            'log' => true,  // Enable logging of module loading
        ],
    ]
];

Module Loader Setup

Using Constructor Style (PHP-DI)

<?php
// config/bootstrap.php
use DI\Container;
use Psr\Log\LoggerInterface;
use Slim\App;

$container->set(\MagmaSoftwareEngineering\Slim\Module\ModuleLoader::class, static function (
    App $app,
    Container $container
): \MagmaSoftwareEngineering\Slim\Module\ModuleLoader {
    $modules = $container->get('settings')['modules'];

    return new \MagmaSoftwareEngineering\Slim\Module\ModuleLoader([
        'app' => $app,
        'modulesPath' => $modules['path'],
        'logger' => isset($modules['log']) && $modules['log'] === true
            ? $container->get(LoggerInterface::class)
            : null,
    ]);
};

Using Fluent Interface Style

<?php
// config/bootstrap.php
use DI\Container;
use Psr\Log\LoggerInterface;
use Slim\App;

$container->set(\MagmaSoftwareEngineering\Slim\Module\ModuleLoader::class, static function (
    App $app,
    Container $container
): \MagmaSoftwareEngineering\Slim\Module\ModuleLoader {
    $modules = $container->get('settings')['modules'];

    return (new \MagmaSoftwareEngineering\Slim\Module\ModuleLoader())
        ->setApp($app)
        ->setModulesPath($modules['path'])
        ->setLogger(isset($modules['log']) && $modules['log'] === true
            ? $container->get(LoggerInterface::class)
            : null)
        ->init();
});

Complete Application Bootstrap

<?php
// public/index.php
require_once dirname(__DIR__) . '/vendor/autoload.php';

use Slim\Factory\AppFactory;
use MagmaSoftwareEngineering\Slim\Module\ModuleLoader;

// Setup dependency container and application
$container = require dirname(__DIR__) . '/config/bootstrap.php';
$app = AppFactory::createFromContainer($container);

// Load all configured modules
$moduleLoader = $container->get(ModuleLoader::class);

// Run application
$app->run();

Complete Application Example

Full Project Structure

my-api/
├── public/
│   └── index.php
├── src/
│   └── modules/
│       ├── User/
│       │   ├── src/
│       │   │   ├── Controller/
│       │   │   │   └── UserController.php
│       │   │   ├── Service/
│       │   │   │   └── UserService.php
│       │   │   ├── Entity/
│       │   │   │   └── User.php
│       │   │   └── dependencies.php
│       │   ├── Module.php
│       │   ├── routes.php
│       │   ├── middleware.php
│       │   └── settings.php
│       ├── Product/
│       │   ├── src/
│       │   │   ├── Controller/
│       │   │   │   └── ProductController.php
│       │   │   ├── Service/
│       │   │   │   └── ProductService.php
│       │   │   └── dependencies.php
│       │   ├── Module.php
│       │   ├── routes.php
│       │   └── settings.php
│       └── Admin/
│           ├── src/
│           │   ├── Controller/
│           │   │   └── AdminController.php
│           │   └── dependencies.php
│           ├── Module.php
│           └── routes.php
├── config/
│   ├── bootstrap.php
│   └── settings.php
└── composer.json

Architecture

Modules enable a plugin-based, composable architecture:

Application Container
    ↓
Module Loader (discovers & initialises modules)
    ├── User Module
    │   ├── dependencies.php → DI configuration
    │   ├── routes.php → API endpoints
    │   ├── middleware.php → Request middleware
    │   └── src/ → Controllers, Services, Entities
    ├── Product Module
    │   ├── dependencies.php
    │   ├── routes.php
    │   └── src/
    └── Admin Module
        ├── dependencies.php
        ├── routes.php
        └── src/

Integration with Other Libraries

This library is a core component of the Magma Software Engineering stack:

Related Libraries

• Slim Base Library - HTTP controllers and framework integration
• Rollout Group Slim - Feature flagging module
• PHP DebugBar Middleware - Debug toolbar module

Support & Contributing

For issues or contributions, please contact the maintainer:

• Jeremy Coates - hello@phpcodemonkey.me.uk

License

MIT License - See LICENSE.md file for details