README

Introduction

This package contains common functions that you can use in your microservices to check authentication, authorization and more.

1. Installation Via Composer

You can install the package via composer:

composer require glc36/maxloop-kernel

2. Installation Locally For Development

Create path following with

<project_root>/packages/glc36/maxloop-kernel

Configure to your composer.json to create a path repository that uses a symlink:

# Switch the minimum-stability from `stable` to `dev`
"minimum-stability": "dev",

# Add the following to end of composer.json
"repositories": [
    {
        "type": "path",
        "url": "packages/glc36/maxloop-kernel",
        "options": {
            "symlink": true
        }
    }
]

Lastly run the following command to require your package:

composer require glc36/maxloop-kernel

3. Configuration

3.1 Maxloop Kernel

3.1.1 Publish Config Assets

This library includes three configuration files for managing your application’s microservices and permissions:

microservice.php: Manages the configuration of the installed microservice.
connector.php: Centralized configuration for all service connectors within your application.
permissions.php: Defines the permissions specific to the installed microservice.

php artisan vendor:publish --tag=maxloop-kernel-config

This library also installed Laravel Kafka package for managing Kafka topics and messages. Hence, kindly run the command above to publish the Kafka config file.

php artisan vendor:publish --tag=laravel-kafka-config

3.1.2 Setting up config variables

Include variables below into your project application's .env and can be use as such: config('microservice.name')

MICROSERVICE_NAME=microservice              // Name of the microservice 
MICROSERVICE_JWT_SIGNATURE=0u5qVEQkmSfhl    // HS256 signature
MICROSERVICE_JWT_TTL=900                    // JWT expiration time in seconds (default: 15 minutes)
MICROSERVICE_REFRESH_JWT_TTL=172800         // Refresh JWT expiration time in seconds (default: 2 days)
MICROSERVICE_JWT_CACHE_TTL=300              // Cache duration in seconds (default: 5 minutes)
MICROSERVICE_AUTH_CONTEXT_CACHE_TTL=600     // Cache duration in seconds (default: 10 minutes)
MICROSERVICE_SHARED_TOKEN=gjyu5yjy8er       // Shared Static Token for Services Internal Communication

3.2 Kafka

3.2.1 Publish Kafka Config Assets

Publish the Kafka configuration file to your config directory.

php artisan vendor:publish --tag=laravel-kafka-config

3.2.2 Setting up Kafka config variables

Include the Kafka environment variables below into your project application's .env

// The kafka broker address (default: localhost:9092)
KAFKA_BROKERS=kafka-service:10000

// The security protocol for Kafka (default: PLAINTEXT)
KAFKA_SECURITY_PROTOCOL=PLAINTEXT

// The consumer group ID for Kafka (default: group)
KAFKA_CONSUMER_GROUP_ID=mms-cas-consumers

// Enable or disable debug mode for Kafka (default: false)
KAFKA_DEBUG=true

// Cache driver (default: file)
KAFKA_CACHE_DRIVER=redis

3.2.3 Publish Service Providers

This library also installed Kafka service provider to bootstrap Kafka core service in your application.:

KafkaServiceProvider: Register Kafka producer services.

php artisan vendor:publish --tag=maxloop-kernel-provider

After publishing, you can add the service providers to your bootstrap/providers.php file:

<?php

return [
    // existing code ...
    App\Providers\KafkaServiceProvider::class,
];

3.2.4 Publish Kafka Supervisor Config Assets

This library also installed Kafka supervisor config file to bootstrap Kafka core service in your application.

php artisan vendor:publish --tag=maxloop-kafka-supervisor

3.2.5 Publish KafkaConsumerCommand to your service (Optional)

This libary includes a KafkaConsumerCommand class to consume Kafka messages. Use the command below to publish the command to your application if needed.

php artisan vendor:publish --tag=maxloop-kafka-commands

Kindly refer to Kafka documentation for more information on how to use the command.

4. Cache Generator Helper

The CacheGenerator class provides a helper for managing cache operations in our project application. It simplifies common tasks like setting, retrieving, and deleting cache values, with support for microservice-specific cache key prefixes.

4.1 Features

Automatically prefixes cache keys with a microservice name.
Supports setting cache with a time-to-live (TTL) or permanently.
Retrieves cache values.
Deletes individual cache values.
Deletes all cache values for a specific microservice.

4.2 Notes

Ensure your project application has the required dependencies, such as Redis for cache storage, and include this helper in your project.

4.3 Configuration

The CacheGenerator class uses the following configurations:

microservice.name: The name of the microservice used as a prefix for cache keys.
database.redis.cache.database: Specifies the Redis database used for caching.

Ensure these configurations are defined in your config files.

4.4 Constructor

Creates a new CacheGenerator instance with the given key.

$cache = new CacheGenerator(string $key);

4.5 Set a Cache Value

Sets a value in the cache with an optional TTL (time-to-live).

$cache->set(array|string|null $value, ?int $ttl = null): bool

4.6 Get a Cache Value

Retrieves a value from the cache.

$cache->get(): mixed

Pass a closure as the default value and store it, if the requested cache doesn't exist

$cache->get(function () use ($request) {
    // If cache data not found, retrieve data again
    return DB::table('users')->get();
}, 100); // Set cache TTL—if not set, it will be store forever.

4.7 Delete a Specific Cache Entry

Deletes the specific cache value associated with the key.

$cache->delete(): bool

4.8 Delete All Cache Entries for a Microservice

Deletes all cache entries for the microservice by scanning for keys with the microservice prefix.

CacheGenerator::deleteAll(): bool

Deleting all cache from a microservice only supported in redis driver

5. ApiResponse Utility Class

The ApiResponse class provides a standardized way to return JSON responses in our project application. It simplifies handling success, error, validation, and paginated responses.

5.1 Method

success

A method for generating a success response.

public static function success(string $message, array|LengthAwarePaginator $data, int $statusCode = JsonResponse::HTTP_OK): JsonResponse

Parameters:

string $message: The success message.
array $data: Additional data to include in the response body (optional).
int $statusCode: HTTP status code (default is 200).

Example:

return ApiResponse::success('Operation Successfully', ['key' => 'value'], 200)

error

A method for generating a error response.

public static function error(string $message, array $data = null, int $statusCode = JsonResponse::HTTP_BAD_REQUEST): JsonResponse

Parameters:

string $message: The error message.
array $data: Additional error details (optional).
int $statusCode: HTTP status code (default is 400).

Example:

return ApiResponse::error('An Error Occurred', ['key' => 'value'], 400)

validationException

Handles and formats validation exceptions.

public static function validationException(ValidationException $exception): JsonResponse

Parameters:

ValidationException $exception: The validation exception instance.

Example:

return ApiResponse::validationException($exception);

Response Format:

{
  "status": false,
  "message": "Validation Error: Ensure All Fields Are Correctly Filled",
  "body": {
    "field": ['field1' => ['The Field1 Is Required']]
  }
}

exceptionError

Handles and formats general exceptions.

public static function exceptionError(Exception $exception, string $message = null): JsonResponse

Parameters:

Exception $exception: The general exception instance.
string $message: The exception error message.

Example:

return ApiResponse::exceptionError($exception);

Response Format:

{
  "status": false,
  "message": "General Error Occurred",
  "body": null
}

6. Custom Exception Handling

The MaxloopExceptionBaseClass class that provides a robust exception handling system and standardized API responses for Laravel applications.

6.1 Features

Easily handle exceptions and return standardized error responses.
Automatically format validation errors in a consistent structure.
Easily extend and customize the exception handling logic.
Simplify API responses with success and error response helpers.

6.2 Usage

To automatically transform any exception and render as ApiResponse json response, register the handler in your bootstrap/app.php file:

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(...)
    ->withMiddleware(...)
    ->withExceptions(function (Exceptions $exceptions) {
        $exceptions->renderable(function (\Exception $exception, $request) {
            if ($request->is('*api*') || $request->wantsJson()) {
                $handler = new MaxloopExceptionBaseClass();
                return $handler->render($request, $exception);
            }
        });
    })->create();

$request->is(" api ") (Optional to check the path contain "api")

$request->wantsJson() (Optional to check client wants the response as JSON format -> Accept: application/json)

6.3 Examples

Handling Validation Errors

When a validation error occurs, the response will look like this

{
    "status": false,
    "message": "Validation Error: Ensure All Fields Are Correctly Filled",
    "data": {
        "email": ["The email must be a valid email address."]
        }
}

Custom Exception Handling

When a exception error occurs, the response will look like this

{
    "status": false,
    "message": "General Error Occurred",
    "data": null
}

7. JWT Handler

7.1 📌 Overview

JwtHandler is a utility class for managing JWT (JSON Web Tokens) in your application using the tymon/jwt-auth package.
It provides methods for generating, validating, retrieving, and invalidating JWT tokens.

7.2 ⚙️ Features

✅ Generate JWT tokens with custom claims
✅ Validate JWT tokens (including expiration and signature checks)
✅ Retrieve all or specific claims from a token
✅ Validate user roles and permissions
✅ Invalidate a JWT token (Delete from cache)

Prerequisites

You can publish jwt config file with:

php artisan vendor:publish --provider="Tymon\JWTAuth\Providers\LaravelServiceProvider"

The jwt secret key, ttl or etc. can be setup in kernel config file.

7.3 Generating a JWT Token

To generate a token for a user with custom claim

$jwtHandler = new JwtHandler();
$tokenData = $jwtHandler->signToken($user, 'admin', ['role' => 'admin'], $setCache);

7.4 Set jwt token

Set a jwt token

$jwtHandler = new JwtHandler();
$jwtHandler->setToken($token);

7.5 Validating a JWT Token

Validate JWT Token

$jwtHandler->isValidAccessToken()

7.6 Retrieving Claims or Claim from JWT

Retrieve all or specific claims from a jwt token

$claims = $jwtHandler->getClaims(); // Get all claims
$role = $jwtHandler->getClaim('role'); // Get specific claim

7.7 Invalidating a JWT Token

Invalidate a JWT Token and delete from cache

$jwtHandler->invalidateJwtToken();

8. Auth Context Handler

8.1 📌 Overview

AuthContextHandler class provides a centralized way to manage Authorization Context in your application using caching. It allows setting, retrieving, and validating a user's roles and permissions using their UUID.

8.2 ⚙️ Features

✅ Store and retrieve user auth context from cache
✅ Validate if auth context exists or fetch a fresh one
✅ Check user authorization using roles or permissions
✅ Supports either_one or required_all authorization conditions
✅ Works seamlessly with CasConnector and CacheGenerator services

Prerequisites

You can set auth context cache in .env:

MICROSERVICE_AUTH_CONTEXT_CACHE_TTL=600

Can refer to microservice config file.

8.3 Set UUID

Set a user's UUID

$authContextHandler->setUuid('user-uuid-1234');

8.4 Set Auth Context

Set user's auth context in cache

$authContextHandler->setContext([
    'roles' => ['admin', 'editor'],
    'permissions' => ['manage.users', 'edit.articles'],
]);

8.5 Get Auth Context

Get auth context from cache (Either return data or boolean)

$context = $authContextHandler->getContext();
$hasContext = $authContextHandler->getContext(true); // returns true or false

8.6 Validate Auth Context

Validates and refreshes context if needed

$isValid = $authHandler->validateContext();

8.7 Authorization Checks

Check if is authorized on user roles or permissions.

// Check if user has ANY of these roles/permissions
$hasAccess = $authHandler->isAuthorized(['admin', 'editor']);

// Check if user has ALL of these roles/permissions
$hasAllAccess = $authHandler->isAuthorized(
    ['admin', 'publisher'], 
    AuthContextHandler::CONDITION_REQUIRED_ALL
);

9. Middleware

This library contains THREE middleware classes for your application:

JwtAuthMiddleware: Validates JWT tokens before processing requests.
AuthContextMiddleware: Middleware to validate and preload the authenticated user's context into cache based.
Authorization Middleware: Middleware for handling role and permission based authorization.

9.1 🔹 JwtAuthMiddleware

The JwtAuthMiddleware ensures that a valid JWT token is present in requests.

9.1.1 ⚙️ Features

✅ Extracts the JWT token from the Authorization header.
✅ Validates the token using JwtHandler.
✅ Blocks unauthorized access.

9.1.2 📌 Installation

use Glc36\MaxloopKernel\Middleware\JwtAuthMiddleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->api(append:[JwtAuthMiddleware::class]);
})

[!IMPORTANT] For CAS microservice change the value CAS_CONNECTOR_STRATEGY in .env
Can refer to connector.php file By changing to controller the app will call to it own controller's method instead of calling API endpoint

CAS_CONNECTOR_STRATEGY=controller

9.2 🔹 AuthContextMiddleware

The AuthContextMiddleware sets up the user's authorization context for subsequent requests in the application lifecycle.

9.2.1 📌 Installation

use Glc36\MaxloopKernel\Middleware\AuthContextMiddleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->api(append:[AuthContextMiddleware::class]);
})

9.3 🔹 Authorization Middleware (New Method)

The Authorization middleware restricts access to routes based on user roles or permissions.

9.3.1 ⚙️ Features

✅ Supports single role/permission, multiple required roles/permissions (AND condition), and either one of multiple roles/permissions (OR condition).
✅ Extracts roles/permissions from the User Token Cache.
✅ Uses a custom Authorize Guard for role/permission validation.

9.3.2 📌 Installation

use Glc36\MaxloopKernel\Middleware\AuthorizationMiddleware;

->withMiddleware(function (Middleware $middleware) {
    $middleware->alias([
        'authorization' => AuthorizationMiddleware::class
    ]);
})

9.3.3 Usage

After you have registered the aliases as shown above, you can use them in your Routes and Controllers much the same way you use any other middleware:

// Single role or sing permission
Route::group(['middleware' => ['authorization:admin']], function () { ... });
Route::group(['middleware' => ['authorization:cas.user.users.view']], function () { ... });

// Multiple required roles and permissions (AND condition)
Route::group(['middleware' => ['authorization:admin,cas.user.users.view']], function () { ... });

// Either one of the roles or permissions (OR condition: must have AT LEAST ONE role or ONE permission)
Route::group(['middleware' => ['authorization:admin|cas.user.users.view']], function () { ... });

10. Service to Service Connector

Connector is a microservice-specific connector that provides a convenient way to interact with every microservice between your application.

10.1 📌 Installation

Define the services in your config/connector.php file

// Global Base URL for communication (Thru API Gateway)
'base_url' => env('CONNECTOR_BASE_URL'),
// Each microservice unique name, can refer to their microservice name
'cas' => [
    // The human-readable name of the service. (Only for display purpose)
    'name' => 'Centralize Authentication Service',

    // Default strategy is API (api or controller)
    'strategy' => env('CAS_CONNECTOR_STRATEGY', 'api'),

    // Controller route name
    'controllers' => [
        'validate_access_token' => 'api.public.validate.access-token',
        'revoke_token' => 'api.revoke.token',
        'revoke_tokens_by_entity' => 'api.revoke.tokens'
    ]
],

base_url: Global Base URL for communication (Thru API Gateway).
strategy: The strategy for connect which can be either 'api' (via HTTP request) or 'controller' (direct method call).
controllers: Route names used for direct controller calls

10.2 🔹 CasConnector

It facilitates communication with the CAS (Central Authentication Service) by providing methods for validating access tokens and auth context.

10.2.1 Validating an Access Token

Validate a JWT token with the CAS service.

$casConnector = new CasConnector();
// Will pass bearer token in header to the endpoint for validation
$response = $casConnector->validateAccessToken();

10.2.2 Retrieve User Auth Context

Retrieve user auth context on sensitive data such as roles, permissions, tenant id and etc.

$casConnector = new CasConnector();
// Will pass bearer token in header to the endpoint
$response = $casConnector->getAuthContext();

10.3 🔹 InternalServiceConnector

It facilitates communication between services by defining internal endpoint and HTTP method.

10.3.1 Configure Microservice Shared Token

Set shared microservice token in .env.

MICROSERVICE_SHARED_TOKEN=asdvcxvcxv

10.3.2 Call Endpoint

Call to services internal endpoint.

$internalConnector = new \Glc36\MaxloopKernel\Services\InternalServiceConnector();
// Will pass shared token in header to the endpoint for authentication
$response = $internalConnector->callEndpoint('get', '/general/api/internal/v1/currencies');

10.4 🔹 MediaConnector

It facilitates communication with the Media (Media Service) by providing methods for upload, retrieve and delete media.

10.4.1 📌 Installation

Set filesystem disk that you wished to use in .env.

MEDIA_DISK=local

If uses the local disk, should create a symbolic link from source directory
To create the symbolic link, you may use the storage:link Artisan command

php artisan storage:link

10.4.2 Retrieve, Delete and Upload Media

Retrieve, Delete and Upload a media item to the Media Service.

$mediaConnector = new MediaConnector();
// Will pass shared token in header to the endpoint for authentication
$response = $mediaConnector->uploadMedia([
    'file' => file_get_contents($path),
    'directory' => 'media', // file location
    'thumbnail' => true // boolean either want to create a thumbnail
]);

$response = $mediaConnector->retrieveMedia(1); // Pass media ID
$response = $mediaConnector->deleteMedia(1); // Pass media ID

11. Logging with Loki (installation process)

This package supports logging to Grafana Loki. Follow these steps to configure it:

11.1 Configure Loki Channel

Add the following configuration to your microservice's config/logging.php file under the channels array:

   'loki' => [
       'driver' => 'monolog',
       'handler' => \Glc36\MaxloopKernel\Services\LokiHandler::class,
       'formatter' => Monolog\Formatter\JsonFormatter::class,
       'with' => [
           'url' => env('LOKI_ENDPOINT', 'http://loki:3100/loki/api/v1/push'),
           'labels' => [
               'label' => env('MICROSERVICE_NAME', 'unknown-microservice'),
               'service_name' => 'microservice',
           ],
       ],
   ],

11.2 Set the default log channel

Update the .env file:

   LOG_CHANNEL=loki // Default log channel
   LOKI_ENDPOINT=http://loki:3100/loki/api/v1/push

11.3 Clear and cache configuration

   php artisan config:clear
   php artisan config:cache

11.4 Middleware

AddRequestHeaderToLog

This package includes the AddRequestHeaderToLog middleware to capture request headers in logs. Register it in your Laravel project's middleware stack in bootstrap/app.php:

use Glc36\MaxloopKernel\Middleware\AddRequestHeaderToLog;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->append(AddRequestHeaderToLog::class);
    })
    ->create();

11.5 Logging Helper

Audit Logging Helper

The LogHelper class provides an audit() method to log model changes (create, update, delete). It only stores affected fields rather than the entire model.

Usage Example

use Glc36\MaxloopKernel\Helpers\LogHelper;

LogHelper::audit('User updated', 'update', $user);

11.6 Loggable Trait

To automatically log model events (created, updated, deleted), you can use the Loggable trait in your models:

use Glc36\MaxloopKernel\Traits\Loggable;

class User extends Model
{
    use Loggable;
    
    // ... rest of your model code
}

This will automatically log:

When a model is created
When a model is updated (including only changed fields)
When a model is deleted

The trait will automatically:

Generate appropriate log messages
Capture the event type
Include the model data
Add context from JWT tokens
Include request metadata

11.6 Log Format Example

{
  "log_message": {
    "message": "User updated",
    "context": {
      "context": 1741358490000,
      "tenant_id": "12345",
      "entity_id": "1",
      "entity_type": "App\\Models\\User"
    },
    "level": 200,
    "level_name": "INFO",
    "channel": "loki",
    "datetime": "2025-03-07T14:39:17.835317Z",
    "extra": {
      "event_type": "update",
      "old_data": {
        "name": "John Doe"
      },
      "new_data": {
        "name": "John Smith"
      }
    }
  },
  "metadata": {
    "url": "http://127.0.0.1/users/1",
    "method": "PATCH",
    "user_agent": "Mozilla/5.0",
    "ip": "192.168.1.1",
    "request_id": "abcd-1234",
    "route_name": "users.update"
  }
}

11.7 Log Structure

The log structure consists of two main parts:

log_message: Contains the core log information
- message: The log message
- context: Additional context including:
  - context: Unix timestamp
  - tenant_id: Tenant identifier from JWT token
  - entity_id: ID of the affected model
  - entity_type: Class name of the affected model
- level: The log level (numeric)
- level_name: The log level name (e.g., "INFO")
- channel: The logging channel (loki)
- datetime: ISO timestamp of the log entry
- extra: Additional data including:
  - event_type: Type of event (create, update, delete)
  - old_data: Previous values of changed fields (for update events)
  - new_data: New values of changed fields
metadata: Contains request-related information
- url: The full URL of the request
- method: HTTP method used
- user_agent: Client's user agent
- ip: Client's IP address
- request_id: Unique request identifier
- route_name: Name of the route being accessed

11.8 Notes

The audit() method only stores changed fields for update events to minimize log size
Tenant ID is automatically captured from JWT token claims if present
The token should be provided in the Authorization header
If the token is invalid or missing, tenant_id will be null
Request metadata is automatically captured through the AddRequestHeaderToLog middleware
All timestamps are in ISO 8601 format with timezone information
The logger handles special characters and quotes in data fields
The logger supports models with relationships and custom attributes

12. Queue Job Base Extender

It automatically prefixes the job queue name with the microservice name and adds the microservice name as a job tag for easy identification and monitoring.

12.1 ⚙️ Features

✅ Automatically appends the microservice name to the queue job name.
✅ Adds the microservice name as a tag for job tracking.
✅ Supports easy customization via a config file.

12.2 🚀 Usage

Extends BaseJob in your job file:

use Glc36\MaxloopKernel\Jobs\BaseJob;

class TestJob extends BaseJob
{
    public function __construct()
    {
        parent::__construct();
    }

    protected function queueName(): string
    {
        return 'test-job';
    }

    public function handle()
    {
        // Your job logic here
        \Log::info('Processing data...');
    }
}

12.3 Optional: Customize Further

If you need to customize the tags further, you can override the tags methods in your specific job class.

public function tags(): array
{
    // Additional tags
    return array_merge(parent::tags(), ['additional_tag']);
}

13. HttpClient Utility (API Client)

The HttpClient utility provides a standardized way to make HTTP requests in your application. It simplifies common HTTP operations with pre-configured settings and error handling.

13.1 📌 Overview

HttpClient is a wrapper around Guzzle HTTP client that provides consistent request handling, logging, and error management for your microservices.

13.2 ⚙️ Features

✅ Pre-configured with sensible defaults for microservice communication
✅ Automatic request logging
✅ Standardized error handling
✅ Support for authentication headers
✅ Configurable timeout and retry settings

13.3 Configuration

The HttpClient uses the following configurations from the http-client.php config file:

php artisan vendor:publish --tag=maxloop-kernel-config --force

13.4 Configure your HTTP client settings in the .env file:

HTTP_CLIENT_TIMEOUT=30           # Request timeout in seconds
HTTP_CLIENT_RETRY_TIMES=3        # Number of retry attempts
HTTP_CLIENT_RETRY_SLEEP=1000     # Sleep between retries in milliseconds

HTTP_PROXY=true
HTTP_PROXY_HOST='54.251.100.169'
HTTP_PROXY_PORT='3128'
HTTP_PROXY_TYPE=http
HTTP_PROXY_USERNAME=
HTTP_PROXY_PASSWORD=

13.5 Basic Usage

Create a new HttpClient instance and make requests:

use Glc36\MaxloopKernel\Services\HttpClient;

$httpClient = new HttpClient();

// GET request
$response = $httpClient->get('https://api.example.com/users');

// POST request with JSON data
$response = $httpClient->post('https://api.example.com/users', [
    'name' => 'John Doe',
    'email' => 'john@example.com'
]);

// PUT request
$response = $httpClient->put('https://api.example.com/users/1', [
    'name' => 'Updated Name'
]);

// DELETE request
$response = $httpClient->delete('https://api.example.com/users/1');

13.6 Advanced Usage

13.6.1 Response methods

Reference: https://laravel.com/docs/11.x/http-client#introduction

$response = $httpClient->get('https://api.example.com/users');

$response->body() : string;
$response->json($key = null, $default = null) : mixed;
$response->object() : object;
$response->collect($key = null) : Illuminate\Support\Collection;
$response->resource() : resource;
$response->status() : int;
$response->successful() : bool;
$response->redirect(): bool;
$response->failed() : bool;
$response->clientError() : bool;
$response->header($header) : string;
$response->headers() : array;

13.6.2 Custom Headers

$response = $httpClient->withHeaders([
    'X-Custom-Header' => 'Custom Value',
    'Accept' => 'application/json',
    'Content-Type' => 'application/json'
])->get('https://api.example.com/users');

13.6.3 Authentication

// Bearer token authentication
$response = $httpClient->withToken('your-access-token')
    ->get('https://api.example.com/protected-resource');

13.6.4 Custom Options

$response = $httpClient->withOptions([
    'timeout' => 60,
    'connect_timeout' => 20,
    'verify' => false  // Disable SSL verification (not recommended for production)
])->get('https://api.example.com/users');

13.6.5 Error Handling

try {
    $response = $httpClient->get('https://api.example.com/users');
    $data = $response->json();
} catch (Illuminate\Http\Client\HttpClientException $e) {
    // Handle client errors (4xx)
    $statusCode = $e->getStatusCode();
    $errorMessage = $e->getMessage();
} catch (\Exception $e) {
    // Handle other exceptions
}

glc36 / maxloop-kernel

Maintainers

Details

README

Introduction

1. Installation Via Composer

2. Installation Locally For Development

3. Configuration

3.1 Maxloop Kernel

3.1.1 Publish Config Assets

3.1.2 Setting up config variables

3.2 Kafka

3.2.1 Publish Kafka Config Assets

3.2.2 Setting up Kafka config variables

3.2.3 Publish Service Providers

3.2.4 Publish Kafka Supervisor Config Assets

3.2.5 Publish KafkaConsumerCommand to your service (Optional)

4. Cache Generator Helper

4.1 Features

4.2 Notes

4.3 Configuration

4.4 Constructor

4.5 Set a Cache Value

4.6 Get a Cache Value

4.7 Delete a Specific Cache Entry

4.8 Delete All Cache Entries for a Microservice

5. ApiResponse Utility Class

5.1 Method

6. Custom Exception Handling

6.1 Features

6.2 Usage

6.3 Examples

Handling Validation Errors

Custom Exception Handling

7. JWT Handler

7.1 📌 Overview

7.2 ⚙️ Features

7.3 Generating a JWT Token

7.4 Set jwt token

7.5 Validating a JWT Token

7.6 Retrieving Claims or Claim from JWT

7.7 Invalidating a JWT Token

8. Auth Context Handler

8.1 📌 Overview

8.2 ⚙️ Features

8.3 Set UUID

8.4 Set Auth Context

8.5 Get Auth Context

8.6 Validate Auth Context

8.7 Authorization Checks

9. Middleware

9.1 🔹 JwtAuthMiddleware

9.1.1 ⚙️ Features

9.1.2 📌 Installation

9.2 🔹 AuthContextMiddleware

9.2.1 📌 Installation

9.3 🔹 Authorization Middleware (New Method)

9.3.1 ⚙️ Features

9.3.2 📌 Installation

9.3.3 Usage

10. Service to Service Connector

10.1 📌 Installation

10.2 🔹 CasConnector

10.2.1 Validating an Access Token

10.2.2 Retrieve User Auth Context

10.3 🔹 InternalServiceConnector

10.3.1 Configure Microservice Shared Token

10.3.2 Call Endpoint

10.4 🔹 MediaConnector

10.4.1 📌 Installation

10.4.2 Retrieve, Delete and Upload Media

11. Logging with Loki (installation process)

11.1 Configure Loki Channel

11.2 Set the default log channel

11.3 Clear and cache configuration

11.4 Middleware

AddRequestHeaderToLog

11.5 Logging Helper

Audit Logging Helper

Usage Example