README

Version: 1.x | PHP: >=8.5 | 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: >=8.5
slim/slim: ^4.15 (HTTP framework)
slim/psr7: ^1.8 (PSR-7 implementation)
psr/http-message: ^2.0 (HTTP message interfaces)
psr/log: ^3.0 (Logging interface)

Installation

Installation is only supported through Composer:

composer require magmasoftwareengineering/slim-module-middleware:^2.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:

Library	Purpose	Integration
Slim Base	HTTP controllers & settings	Inherit AbstractController in your modules
Doctrine Base	Database entities & repositories	Use via DI in module dependencies.php
Rollout Group Slim	Feature flagging	As a middleware module for feature flags
PHP DebugBar Middleware	Developer debugging	As a middleware module for debugging

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