kroderdev / laravel-microservice-core
A toolkit to use Laravel effectively as a microservice in a distributed architecture.
Requires
- php: >=8.1
- firebase/php-jwt: ^6.0
- illuminate/support: ^10.0|^11.0|^12.0
Requires (Dev)
- orchestra/testbench: ^10.4
- phpunit/phpunit: ^11.5
README
A toolkit to leverage Laravel 12 as a performant and configurable microservice framework within distributed architectures.
Overview
This package provides a robust foundation for building Laravel-based microservices, focusing on stateless authentication, authorization, and distributed system best practices. Out of the box, you’ll find:
-
JWT Authentication Middleware:
Securely validates JWT tokens and hydrates the authenticated user for each request. -
Role & Permission Middleware:
Restrict access to routes based on user roles or permissions, with support for both JWT-embedded and dynamically loaded access control. -
LoadAccess Middleware:
Optionally fetches the latest roles and permissions for the authenticated user from a centralized permission service or API Gateway. -
Correlation ID Middleware:
Automatically generates or propagates a unique correlation ID for every request, enabling end-to-end tracing across distributed systems. -
Configurable Middleware Aliases & Groups:
Easily enable, disable, or rename middleware via configuration, and use convenient groups likemicroservice.authgroup for full authentication and authorization in one step. -
HTTP Client Macros:
Pre-configured HTTP clients for communicating with your API Gateway or other services. -
Ready-to-publish Configuration:
All settings are customizable via a single config file, making it easy to adapt the package to your environment.
This toolkit is designed to be flexible, extensible, and easy to integrate into any Laravel microservice architecture.
Installation
Install directly from Packagist via Composer:
- Require the package via Composer:
composer require kroderdev/laravel-microservice-core
Note
To install the dev branch, append :dev-main to the package name.
Publish Configuration
After installation, publish the configuration file to your Laravel project:
php artisan vendor:publish --provider="Kroderdev\LaravelMicroserviceCore\Providers\MicroserviceServiceProvider"
You can now customize the settings to match your microservice environment.
Middlewares
This package provides a set of middleware designed to enhance your Laravel microservice with common cross-cutting concerns. You can enable, disable or rename each middleware by editing the middleware_aliases section in config/microservice.php.
// config/microservice.php 'middleware_aliases' => [ 'jwt_auth' => 'jwt.auth', // alias for JWT Authentication middleware 'correlation_id' => 'correlation.id', // alias for Correlation ID middleware 'disabled_mw' => '', // empty string disables a middleware ],
JWT Authentication
Alias: the string you assign to jwt_auth in middleware_aliases, e.g. jwt.auth.
Class: Kroderdev\LaravelMicroserviceCore\Http\Middleware\ValidateJwt
Description
Validates the presence and integrity of a JSON Web Token (JWT) in the Authorization header of incoming requests. On success, the decoded payload is attached to the request for downstream use; on failure, a 401 response is returned.
Configuration (config/microservice.php)
'auth' => [ 'jwt_public_key' => env('JWT_PUBLIC_KEY_PATH'), 'jwt_algorithm' => env('JWT_ALGORITHM', 'RS256'), 'jwt_cache_ttl' => env('JWT_CACHE_TTL', 3600), 'header' => 'Authorization', 'prefix' => 'Bearer', ],
Usage
Register the middleware on routes or globally:
// In routes/api.php Route::middleware(['jwt.auth'])->group(function () { // protected routes… });
Example Response on Failure
// Missing or invalid token { "error": "unauthorized", "message": "Invalid or expired token" }
LoadAccess
Alias: the string you assign to load_access in middleware_aliases, e.g. load.access.
Class: Kroderdev\LaravelMicroserviceCore\Http\Middleware\LoadAccess
Description
Loads the authenticated user's roles and permissions, typically from a centralized permission service (such as an API Gateway or dedicated permissions microservice).
By default, the ValidateJwt middleware will automatically load roles and permissions from the JWT payload if they are present.
However, if you have a centralized permission service, you can use LoadAccess to fetch and hydrate the latest roles and permissions for the user, ensuring up-to-date authorization data.
Usage
Apply after JWT authentication, or use the microservice.auth group for both:
// In routes/api.php Route::middleware(['jwt.auth', 'load.access'])->group(function () { // protected routes with up-to-date permissions… }); // Or simply: Route::middleware('microservice.auth')->group(function () { // protected routes… });
Permission Middleware
Alias: the string you assign to permission in middleware_aliases, e.g. permission.
Class: Kroderdev\LaravelMicroserviceCore\Http\Middleware\PermissionMiddleware
Description
Restricts access to routes based on user permissions.
Checks if the authenticated user has the required permission(s) before allowing access.
Returns a 403 Forbidden response if the user lacks the necessary permission.
Usage
// In routes/api.php Route::middleware(['permission:orders.view'])->get('/orders', [OrderController::class, 'index']); Route::middleware(['permission:orders.create'])->post('/orders', [OrderController::class, 'store']);
Role Middleware
Alias: the string you assign to role in middleware_aliases, e.g. role.
Class: Kroderdev\LaravelMicroserviceCore\Http\Middleware\RoleMiddleware
Description
Restricts access to routes based on user roles.
Checks if the authenticated user has the required role(s) before allowing access.
Returns a 403 Forbidden response if the user does not have the required role.
Usage
// In routes/api.php Route::middleware(['role:admin'])->get('/admin', [AdminController::class, 'dashboard']); Route::middleware(['role:manager'])->post('/reports', [ReportController::class, 'generate']);
Correlation ID
Alias: the string you assign to correlation_id in middleware_aliases, e.g. correlation.id.
Class: Kroderdev\LaravelMicroserviceCore\Http\Middleware\CorrelationId
Description
Generates or propagates a unique X-Correlation-ID header for each request, enabling end-to-end tracing across distributed systems. If the incoming request already has the header, it will be reused; otherwise, a new UUID is generated. The header is added to both the request and the response.
Configuration (config/microservice.php)
'correlation' => [ 'header' => 'X-Correlation-ID', 'length' => 36, ],
Usage
Automatically prepended to the api middleware group (when enabled), or apply explicitly:
// In routes/api.php Route::middleware(['correlation.id'])->group(function () { // traced routes… });
Example Header
X-Correlation-ID: 123e4567-e89b-12d3-a456-426614174000
Auth Middleware Group
For convenience, you can use the built-in microservice.auth group, which runs:
- ValidateJwt – decode JWT, hydrate
ExternalUser, setAuth::user() - LoadAccess – fetch roles & permissions via ApiGateway
Usage
// routes/api.php Route::middleware('microservice.auth')->group(function () { // Here you already have a valid ExternalUser with roles & permissions loaded: Route::get('/orders', [OrderController::class, 'index']); Route::post('/orders', [OrderController::class, 'store']); });
You no longer need to stack jwt.auth + load.access manually—just use microservice.auth wherever you need full auth + authorization.
Public Release and Future Goals
This repository is brand new, and I’m excited to develop it further! My plan is to continuously strengthen the core, add more middleware modules, expand test coverage, and refine configuration options.
Your feedback, issues or pull requests are very welcome—together we can shape this toolkit into a reliable, production-ready solution for Laravel microservices. I hope you find it helpful and look forward to your contributions!