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 like microservice.auth group for full authentication and authorization in one step.

• HTTP Client Macros: Pre-configured HTTP clients for communicating with your API Gateway or other services. When a request is available, these macros automatically forward the current correlation ID header.

• 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:

1. 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.

Configuration (config/microservice.php)

'permissions_cache_ttl' => env('PERMISSIONS_CACHE_TTL', 60),

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:

1. ValidateJwt – decode JWT, hydrate ExternalUser, set Auth::user()
2. 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!