README

The App Service package is part of the Esanj microservice ecosystem.
It provides centralized management, permission handling, and connectivity between different services in your Laravel-based projects.

🧩 Features

• Service registration, listing, updating, and deletion via UI or API.
• Permission management per service.
• Extendable configuration to add custom fields and permissions.
• Built-in middleware for permission checks.
• Works seamlessly with esanj/managers and esanj/layout-master packages.

⚙️ Requirements

• PHP: >= 8.2
• Laravel: >= 12.x
• Dependencies:
  • esanj/managers
  • esanj/layout-master

🚀 Installation

Run the following commands in your Laravel project:

Step 1:

composer require esanj/app-service

Step 2:

php artisan app-service:install

The install command will automatically publish static assets and configuration files.

🖥️ UI Usage

After installation, you can access the service management interface via:

Route name: route('services.index')

Direct URL: /{web_prefix}/services

From this interface, you can:

• View the list of services
• Create new services
• Edit existing services
• Delete services

🔗 API Endpoints

The package also exposes a set of RESTful API endpoints for managing services.

All API requests must include a valid token, which can be obtained via the Manager package.

🧠 Configuration

You can extend the service edit page by adding extra fields.

Simply include the path to your custom Blade components inside the configuration file:

'extra_fields' => [
    'page.contents.price.',
],

🔐 Service Permissions

Define service-specific permissions in your configuration file as follows:

'service_permissions' => [
     'transactions.list' => [
         'display_name' => 'List Transactions',
         'description'  => 'Allows viewing the list of all transactions for the service',
     ],
     'transactions.view' => [
         'display_name' => 'View Transaction Details',
         'description'  => 'Allows viewing detailed information of a single transaction',
     ],
     'transactions.create' => [
         'display_name' => 'Create Transaction',
         'description'  => 'Allows creating new transactions within the service',
     ],
     'transactions.update' => [
         'display_name' => 'Update Transaction',
         'description'  => 'Allows updating existing transaction information for the service',
     ],
     'transactions.delete' => [
        'display_name' => 'Delete Transaction',
        'description'  => 'Allows deleting transactions from the service',
     ],
],

Then, run the following command to import permissions into the database:

php artisan app-service:permissions-import

⚡ Middleware Permission Check

To check a service’s permissions, use the built-in middleware:

service.permission:{permission}

If the service does not have the required permission, an appropriate error response will be returned.

Example:

Route::get('/transactions', [TransactionController::class, 'index'])->middleware('service.permission:transactions.list');

🧩 Middleware Token Validation

The middleware with alias service.validation is used to validate incoming JWT tokens.

If the token is valid, its client_id value will be attached to the request as the attribute jwt_client_id.

If the token is invalid or expired, an appropriate error response with status code 401 Unauthorized will be returned.

Example:

Route::get('/transactions', [TransactionController::class, 'index'])
->middleware(['service.validation', 'service.permission:transactions.list']);

The Authorization header must contain the token in the format:Bearer {token}

On successful validation, the middleware extracts the client_id from the token payload and attaches it to the request object.

If the token is missing, invalid, or expired, a JSON response with an error message and HTTP 401 status is returned.

🌐 API-Only Mode

If your project only uses APIs and has no need for the UI, you can enable API-only mode by setting:

'just_api' => env('APP_SERVICE_JUST_API', false)

This disables all UI routes while keeping the full API functionality intact.

🪪 License

This package is part of the Esanj ecosystem and is intended for internal or authorized use within Esanj-based projects.