README

A Laravel package for integrating with SAP ICF (Internet Communication Framework) services with dynamic SAP client support.

Features

Automatically appends the SAP client parameter to every request (e.g., ?sap-client=500)
Per-request client override via payload key matching SAP_CLIENT_PARAMETER (default: sap-client)
Supports multiple clients via optional .env keys (e.g., SAP_CLIENT_888, SAP_CLIENT_820)
Works with different client parameter names (e.g., sap-client, client, sapclient, etc.)
Helpful config validation and debug helpers

Installation

composer require shakegwapo/sap-icf-service

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="Shakegwapo\SapIcfService\SapServiceProvider" --tag="config"

Config/sap.php


return [
    'base_url'         => env('SAP_BASE_URL', 'https://your-sap-base-url.com'),
    'username'         => env('SAP_USERNAME', 'your-username'),
    'password'         => env('SAP_PASSWORD', 'your-password'),

    // Default client (used unless a per-request override is provided)
    'sap_client'       => env('SAP_CLIENT', '500'),

    // Optional, named clients
    'sap_client_888'   => env('SAP_CLIENT_888', '500'),
    'sap_client_820'   => env('SAP_CLIENT_820', '500'),

    // The parameter name appended to endpoints (e.g., ?sap-client=100)
    'client_parameter' => env('SAP_CLIENT_PARAMETER', 'sap-client'),
];

Configure your .env file:

# SAP connection
SAP_BASE_URL=https://your-sap-server.com
SAP_USERNAME=your-username
SAP_PASSWORD=your-password

# Which query key the API expects for the client (default shown)
SAP_CLIENT_PARAMETER=sap-client

# Default client (fallback when no override is provided)
SAP_CLIENT=500

# Optional: additional, named clients for convenience
SAP_CLIENT_888=888
SAP_CLIENT_820=820

Different SAP API Parameter Names

Some SAP APIs use different client parameter names. Set the correct key via SAP_CLIENT_PARAMETER:

# Standard SAP ICF (default)
SAP_CLIENT_PARAMETER=sap-client

# Other examples (set ONE)
# SAP_CLIENT_PARAMETER=client
# SAP_CLIENT_PARAMETER=sapclient
# SAP_CLIENT_PARAMETER=sap_client

Usage

Basic Usage

The service automatically appends the SAP client parameter to all requests:

use Shakegwapo\SapIcfService\SapService;

$sapService = new SapService();

// GET request - automatically appends ?sap-client=100
$response = $sapService->get('zproduct_order/list');

// POST request - automatically appends ?sap-client=100
$data = ['product_id' => 123, 'quantity' => 5];
$response = $sapService->post('zproduct_order/create', $data);

// PUT request - automatically appends ?sap-client=100
$response = $sapService->put('zproduct_order/update/123', $data);

// DELETE request - automatically appends ?sap-client=100
$response = $sapService->delete('zproduct_order/delete/123');

Per-Request Client Override (NEW)

If your app serves multiple SAP clients, you can override the client for a single request by including a key in the payload matching SAP_CLIENT_PARAMETER (default sap-client).

When present, this value overrides the configured default client.

// Choose client dynamically (e.g., based on a purchase order property)
$response = $sapService->post('purchase-orders/cancel', [
    'sap-client' => ($purchaseOrder->client === '888')
        ? config('sap.sap_client_888')
        : config('sap.sap_client_820'),
    'sap_id'     => '4200000031',
    'rel_code'   => '01',
]);
// => .../purchase-orders/cancel?sap-client=888  (or 820)
// The override only applies to this request.

Notes

The override key must match config('sap.client_parameter') (e.g., sap-client, client, etc.). Typically used with methods that send a payload (post, put, patch). If the override is present, it wins over the configured default.

Configuration Validation

The service validates configuration on initialization and will throw an exception if required settings are missing:

try {
    $sapService = new SapService();
} catch (\InvalidArgumentException $e) {
    // Handle missing configuration
    echo $e->getMessage(); // "SAP configuration is incomplete. Please check your config/sap.php file."
}

Debug Configuration

You can check your current configuration (without sensitive data):

$config = $sapService->getConfig();
// Returns: ['base_url' => '...', 'sap_client' => '100', 'client_parameter' => 'sap-client', 'username_set' => true, 'password_set' => true]

Dynamic SAP Client

The SAP client is automatically read from your configuration and appended to all endpoints. You no longer need to manually add ?sap-client=100 to your endpoints.

Before (old way):

$data = (object)$this->sapService->post('zproduct_order/create?sap-client='.config('sap.sap_client'), $array);

After (new way):

$data = (object)$this->sapService->post('zproduct_order/create', $array);

Endpoint Examples

The service intelligently handles query parameters:

// Simple endpoint
$response = $sapService->get('zproduct_order/list');
// Results in: zproduct_order/list?sap-client=100

// Endpoint with existing parameters
$response = $sapService->get('zproduct_order/list?status=active');
// Results in: zproduct_order/list?status=active&sap-client=100

// POST with data
$response = $sapService->post('zproduct_order/create', ['product_id' => 123]);
// Results in: zproduct_order/create?sap-client=100

Different Parameter Names

If your SAP API uses different parameter names, configure it in your .env:

# For APIs that use 'client' instead of 'sap-client'
SAP_CLIENT_PARAMETER=client

# For APIs that use 'sapclient' instead of 'sap-client'  
SAP_CLIENT_PARAMETER=sapclient

Then your requests will automatically use the correct parameter:

// With SAP_CLIENT_PARAMETER=client
$response = $sapService->get('zproduct_order/list');
// Results in: zproduct_order/list?client=100

// With SAP_CLIENT_PARAMETER=sapclient
$response = $sapService->get('zproduct_order/list');
// Results in: zproduct_order/list?sapclient=100

Configuration Options

The package supports the following configuration options in config/sap.php:

base_url: Your SAP server base URL
username: SAP username for authentication
password: SAP password for authentication
sap_client: SAP client number (e.g., 100, 200, etc.)
client_parameter: Parameter name for SAP client (default: 'sap-client')

Error Handling

The service includes comprehensive error handling for various HTTP exceptions:

ClientException (4xx errors)
ServerException (5xx errors)
ConnectException (connection issues)
RequestException (general request errors)

All errors are logged and return a standardized error response.

Testing

Run the tests:

composer test

License

MIT License

shakegwapo / sap-icf-service

Maintainers

Package info

Statistics

Security