agungsugiarto / mini-framework
The PHP Mini Framework.
Requires
- php: ^8.1.0
- dragonmantank/cron-expression: ^3.1
- illuminate/broadcasting: ^9.36.3
- illuminate/bus: ^9.36.3
- illuminate/cache: ^9.36.3
- illuminate/collections: ^9.36.3
- illuminate/config: ^9.36.3
- illuminate/console: ^9.36.3
- illuminate/container: ^9.36.3
- illuminate/contracts: ^9.36.3
- illuminate/database: ^9.36.3
- illuminate/encryption: ^9.36.3
- illuminate/events: ^9.36.3
- illuminate/filesystem: ^9.36.3
- illuminate/hashing: ^9.36.3
- illuminate/log: ^9.36.3
- illuminate/macroable: ^9.36.3
- illuminate/pagination: ^9.36.3
- illuminate/pipeline: ^9.36.3
- illuminate/queue: ^9.36.3
- illuminate/session: ^9.36.3
- illuminate/support: ^9.36.3
- illuminate/testing: ^9.36.3
- illuminate/translation: ^9.36.3
- illuminate/validation: ^9.36.3
- illuminate/view: ^9.36.3
- laminas/laminas-diactoros: ^2.17
- laminas/laminas-httphandlerrunner: ^2.1
- nikic/fast-route: ^1.3
- psr/container: ^1.0|^2.0
- psr/http-factory: ^1.0
- psr/http-message: ^1.0.1
- psr/http-server-handler: ^1.0.1
- psr/http-server-middleware: ^1.0.1
- psr/simple-cache: ^1.0
- spatie/flare-client-php: ^1.3
- spatie/ignition: ^1.4
- symfony/console: ^6.0
- symfony/error-handler: ^6.0
- symfony/mime: ^6.0
- symfony/var-dumper: ^6.0
- vlucas/phpdotenv: ^5.4.1
Requires (Dev)
- laravel/pint: ^1.20
- mockery/mockery: ^1.4.4
- phpunit/phpunit: ^9.5.8
Suggests
- laravel/tinker: Required to use the tinker console command (^2.7).
README
PHP Mini Framework is a fast and lightweight micro-framework for building web applications with expressive and elegant syntax. This framework is a fork of Laravel Lumen that has been specifically modified and enhanced with modern PSR standards implementation, with a unique focus on seamless PSR-15 middleware integration using Laravel Pipeline as its dispatcher. This innovative approach delivers optimal performance while maintaining developer-friendly experience and universal middleware compatibility for modern PHP applications.
Table of Contents
- Framework Architecture
- MiddlewareTransformer: The Core
- Installation and Usage
- Testing and Quality Assurance
- Documentation and Resources
- Community & Support
- License
Framework Architecture
PSR Standards Implementation
Modern PSR standards implementation for interoperability (PSR-3, 7, 11, 15):
- PSR-3: Logger Interface with Monolog integration for systematic logging
- PSR-7: HTTP Message Interface (ServerRequest/Response) for standard HTTP communication
- PSR-11: Container Interface with auto-wiring for dependency injection
- PSR-15: HTTP Server Request Handlers & Middleware for processing pipeline
Core Architecture
- Application: Integrated PSR-15 RequestHandler + PSR-11 Container
- HTTP Layer: PSR-7 messages with Laravel-style helpers for development ease
- Routing: Fast nikic/fast-route with intelligent auto-response transformation
- Middleware: PSR-15 pipeline with smart parameter injection and Laravel Pipeline as dispatcher
Key Features
Middleware with Auto Parameter Injection:
// Zero-config parameter injection for middleware 'middleware' => 'throttle:60,1|cache:3600,redis' class ThrottleMiddleware implements MiddlewareInterface { public function __construct( private int $maxAttempts, // Auto: 60 private int $decayMinutes // Auto: 1 ) {} }
Smart Response Transformation:
return $user; // Model → JSON 201 return ['data' => $users]; // Array → JSON return "Hello World"; // String → HTML
MiddlewareTransformer: The Core Innovation
Mini Framework's MiddlewareTransformer
bridges PSR-15 middleware with Laravel Pipeline, enabling seamless integration of any PSR-15 middleware within Laravel's familiar ecosystem.
Core Transform Method:
public function transform(array $middlewares): array { return array_map(function ($middleware) { return function (RequestInterface $request, Closure $next) use ($middleware) { return $this->resolveMiddleware($middleware)->process( $request, new PipelineRequestHandler($next) ); }; }, $middlewares); }
How the Transform Process Works:
-
Input: Array of middleware definitions (strings, classes, instances)
['auth:api', 'throttle:60,5', CustomMiddleware::class]
-
Transform Output: Array of Laravel Pipeline-compatible closures
[ // Auth middleware closure with parameter function($request, $next) { return (new AuthMiddleware('api'))->process( $request, new PipelineRequestHandler($next) ); }, // Throttle middleware closure with parameters function($request, $next) { return (new ThrottleMiddleware(60, 5))->process( $request, new PipelineRequestHandler($next) ); }, // Custom middleware closure function($request, $next) { return (new CustomMiddleware())->process( $request, new PipelineRequestHandler($next) ); } ]
-
Pipeline Execution: Laravel Pipeline processes each closure sequentially
$pipeline = new Pipeline($container); $response = $pipeline ->send($request) ->through($transformedMiddlewares) // Our closures ->then(fn (ServerRequestInterface $request): ResponseInterface => $then($request));
The Bridge Mechanism:
- Each closure receives Laravel Pipeline's
($request, $next)
signature PipelineRequestHandler
converts$next
closure to PSR-15RequestHandlerInterface
- PSR-15 middleware's
process()
method is called with proper interfaces - Response flows back through the pipeline chain
PipelineRequestHandler - The Bridge:
class PipelineRequestHandler implements RequestHandlerInterface { public function __construct(private Closure $next) {} public function handle(ServerRequestInterface $request): ResponseInterface { return ($this->next)($request); // Calls Laravel Pipeline's $next } }
This simple adapter class enables PSR-15 middleware to call the next middleware in Laravel Pipeline by:
- Wrapping Laravel's
$next
closure in PSR-15RequestHandlerInterface
- Converting Pipeline's
$next($request)
call to PSR-15's$handler->handle($request)
- Maintaining the middleware chain flow without breaking either standard
Smart Parameter Injection:
// Definition: 'throttle:100,5' // Resolves to: new ThrottleMiddleware(100, 5) class ThrottleMiddleware implements MiddlewareInterface { public function __construct(private int $maxAttempts, private int $decayMinutes) {} public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface { // Your throttling logic here return $handler->handle($request); } }
Key Benefits:
- Universal Compatibility: Any PSR-15 middleware works instantly
- Pipeline Integration: Maintains Laravel's familiar middleware execution flow
- Smart Resolution: Auto-injection with reflection and container integration
- Performance Optimized: Minimal overhead with efficient closure transformation
PSR-15 Middleware Examples
Basic Middleware:
class CustomMiddleware implements MiddlewareInterface { public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface { $request = $request->withAttribute('processed_at', time()); $response = $handler->handle($request); return $response->withHeader('X-Processed-By', 'CustomMiddleware'); } }
Parameterized Middleware:
class ThrottleMiddleware implements MiddlewareInterface { public function __construct(private int $maxAttempts, private int $decayMinutes) {} public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface { // Throttling logic with injected parameters if ($this->exceedsLimit($request)) { return new JsonResponse(['error' => 'Too many requests'], 429); } return $handler->handle($request); } } // Usage: 'throttle:100,5' auto-injects maxAttempts=100, decayMinutes=5
Performance and Optimization
- Lightweight: Minimal overhead compared to full Laravel framework
- Fast Routing: nikic/fast-route + optimal auto-response transformation
- Smart Middleware: PSR-15 bridge with parameter injection for maximum flexibility
- Exception Safe: Bulletproof pipeline execution with proper error handling
- Terminable Lifecycle: Full support for middleware termination cleanup
Core Dependencies
Core libraries used:
laminas/diactoros
- PSR-7 HTTP message implementationnikic/fast-route
- High-performance routerilluminate/*
- Laravel components (Container, Pipeline, etc.)spatie/ignition
- Advanced error handling and debugging
What Makes Mini Framework Special?
PSR-15 Bridge with Laravel Pipeline - Seamlessly use any PSR-15 middleware within Laravel's pipeline ecosystem without compatibility issues.
Smart Parameter Injection - Auto-inject constructor parameters from middleware definitions using reflection with performance caching.
Universal Middleware Compatibility - Compatible with all existing PSR-15 middleware libraries, enabling code reuse across different frameworks.
Installation and Usage
System Requirements
- PHP 8.1 or higher
- Composer for dependency management
Installation Methods
Create New Application (Recommended)
# Create new application from starter template composer create-project agungsugiarto/mini-application my-app cd my-app
Install Framework Only
# Install framework as dependency
composer require agungsugiarto/mini-framework
Environment Configuration
# Create environment file cp .env.example .env # Configure database and other settings in .env APP_ENV=local APP_DEBUG=true DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_DATABASE=mini_framework
Quick Start - Simple Application
<?php require_once 'vendor/autoload.php'; $app = new Mini\Framework\Application(); // Basic route $app->router->get('/', function () { return 'Hello Mini Framework!'; }); // Route with parameters $app->router->get('/api/users/{id}', function ($id) { return ['user_id' => $id, 'framework' => 'mini']; }); // Route with middleware $app->router->get('/protected', [ 'middleware' => 'auth:api', function () { return 'Protected content'; } ]); $app->run();
Middleware Usage Examples
Global Middleware:
$app->middleware([ 'cors', 'throttle:60,1', CustomLoggerMiddleware::class ]);
Route-Specific Middleware:
$app->routeMiddleware([ 'auth' => AuthMiddleware::class, 'throttle' => ThrottleMiddleware::class, 'cache' => CacheMiddleware::class, ]); $app->router->get('/api/data', [ 'middleware' => 'auth|throttle:100,5|cache:300', function () { return ['data' => 'sensitive information']; } ]);
Pipeline Execution Flow:
// 1. Middleware string parsing 'auth|throttle:100,5|cache:300' // Becomes: ['auth', 'throttle:100,5', 'cache:300'] // 2. MiddlewareTransformer.transform() output [ // Each closure wraps PSR-15 middleware in Laravel Pipeline format function($request, $next) { $authMiddleware = new AuthMiddleware(); // No params return $authMiddleware->process($request, new PipelineRequestHandler($next)); }, function($request, $next) { $throttleMiddleware = new ThrottleMiddleware(100, 5); // Auto-injected params return $throttleMiddleware->process($request, new PipelineRequestHandler($next)); }, function($request, $next) { $cacheMiddleware = new CacheMiddleware(300); // Auto-injected param return $cacheMiddleware->process($request, new PipelineRequestHandler($next)); } ] // 3. Laravel Pipeline execution $pipeline->send($request) ->through($transformedMiddlewares) ->then(fn (ServerRequestInterface $request): ResponseInterface => $then($request)); // Execution order: auth → throttle → cache → route handler → cache ← throttle ← auth
Custom PSR-15 Middleware:
class ApiKeyMiddleware implements MiddlewareInterface { public function __construct(private string $requiredKey) {} public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface { $apiKey = $request->getHeaderLine('X-API-Key'); if ($apiKey !== $this->requiredKey) { return new JsonResponse(['error' => 'Invalid API key'], 401); } return $handler->handle($request); } } // Register and use $app->routeMiddleware(['apikey' => ApiKeyMiddleware::class]); $app->router->get('/secure', ['middleware' => 'apikey:secret123', $handler]);
Testing and Quality Assurance
The framework includes comprehensive testing capabilities with PHPUnit and custom testing traits to ensure code reliability and maintainability.
Running Tests
# Run all tests ./vendor/bin/phpunit # Run with coverage report ./vendor/bin/phpunit --coverage-html coverage # Test specific files ./vendor/bin/phpunit tests/FullApplicationTest.php ./vendor/bin/phpunit tests/Cors/CorsServiceTest.php
Test Configuration
# Copy phpunit configuration cp phpunit.xml.dist phpunit.xml # Customize test environment as needed
Documentation and Resources
Standards & Ecosystem
- PSR-15: HTTP Server Request Handlers | PSR-7: HTTP Message Interface
- Laravel Container | Laravel Pipeline
Project Links
Community & Support
Get Help: GitHub Discussions • Issue Tracker • Documentation
Contribute: Contributors • GitHub Repository
License
MIT License - see LICENSE.md for complete details.
Mini Framework - Combining the power of PSR-15 with the ease of Laravel Pipeline for optimal development experience.