Getting Started

Minimal Setup

Install the package:
```
composer require comsave/soap-client
```

Basic usage example (Laravel or standalone):

use Comsave\SoapClient\Client;

$client = new Client('http://example.com/soap-service?wsdl');
$response = $client->__soapCall('OperationName', ['param1' => 'value1']);

First use case: Fetch a simple SOAP response (e.g., a weather API or legacy system call).

$client = new Client('https://example.com/wsdl/weather.wsdl');
$weather = $client->__soapCall('GetWeather', ['zipCode' => '12345']);

Key Starting Points

WSDL-based initialization: Always pass the WSDL URL to the Client constructor.
Method naming: Use __soapCall() for direct SOAP operations (mirrors SoapClient).
Laravel integration: Register the client in a service provider or use a facade (if extended).

Implementation Patterns

Core Workflows

Service Initialization

WSDL-based: Ideal for structured APIs.

$client = new Client('https://api.example.com/service?wsdl', [
    'trace' => 1, // Enable tracing for debugging
    'exceptions' => true, // Throw exceptions on errors
]);

Non-WSDL: For dynamic endpoints (less common but supported).

$client = new Client(null, [
    'location' => 'https://api.example.com',
    'uri' => 'urn:example',
]);

Request/Response Handling

Payload mapping: Use associative arrays for parameters.

$response = $client->__soapCall('CreateOrder', [
    'orderId' => 'ORD123',
    'items' => [
        ['productId' => 'P1', 'quantity' => 2],
        ['productId' => 'P2', 'quantity' => 1],
    ],
]);

Complex types: Leverage PHP arrays/objects for nested structures (SOAP will serialize them).

Error Handling

Exceptions: Enable exceptions in config to catch SOAP faults.

try {
    $response = $client->__soapCall('FaultyOperation', []);
} catch (\SoapFault $e) {
    // Handle SOAP-specific errors
    Log::error($e->getMessage());
}

Debugging: Use trace to log raw SOAP requests/responses.

$client->setTrace(true); // Enable globally
$request = $client->__getLastRequest(); // Inspect last request
$response = $client->__getLastResponse(); // Inspect last response

Laravel-Specific Patterns

Service Container Binding:

$this->app->bind('soap.client', function ($app) {
    return new Client(config('services.soap.wsdl'), config('services.soap.options'));
});

Config File Example (config/services.php):

'soap' => [
    'wsdl' => env('SOAP_WSDL_URL'),
    'options' => [
        'trace' => env('SOAP_TRACE', false),
        'exceptions' => true,
        'timeout' => 30,
    ],
],

Facade (if extended):

// In a facade class:
public static function call($method, $params) {
    return app('soap.client')->__soapCall($method, $params);
}

Batch Operations

For repeated calls (e.g., bulk processing), reuse the client instance:

$client = new Client('https://api.example.com/wsdl');
foreach ($orders as $order) {
    $client->__soapCall('ProcessOrder', $order);
}

Gotchas and Tips

Common Pitfalls

WSDL Caching
- Issue: WSDL files may change, causing stale cached definitions.
- Fix: Disable caching or manually clear it:
```
$client = new Client('https://api.example.com/wsdl', [
    'cache_wsdl' => WSDL_CACHE_NONE, // Disable caching
]);
```
Namespace/URI Mismatches
- Issue: SOAP faults if the uri (namespace) in options doesn’t match the WSDL.
- Fix: Verify the uri in the WSDL and match it in the client config:
```
$client = new Client(null, [
    'location' => 'https://api.example.com',
    'uri' => 'urn:example:api', // Must match WSDL
]);
```
Complex Data Types
- Issue: PHP arrays/objects may not map correctly to SOAP complex types.
- Fix: Use explicit type hints or cast responses:
```
$response = $client->__soapCall('GetUser', ['id' => 1]);
$user = (array) $response; // Force array conversion if needed
```

Timeouts and Performance

Issue: Long-running SOAP calls may time out.

Fix: Adjust timeout and connection_timeout:

$client = new Client('https://api.example.com/wsdl', [
    'timeout' => 60, // 60 seconds
    'connection_timeout' => 10, // 10 seconds to connect
]);

SOAP Headers

Issue: Some APIs require headers (e.g., authentication).

Fix: Use __setSoapHeaders():

$header = new \SoapHeader('urn:auth', 'AuthToken', ['token' => 'abc123']);
$client->__setSoapHeaders([$header]);

Deprecated Methods
- Issue: The package is last updated in 2020; some PHP/SoapClient behaviors may have changed.
- Fix: Test thoroughly and handle edge cases (e.g., SoapClient deprecations in PHP 8+).

Debugging Tips

Enable Tracing

$client->setTrace(true);
$lastRequest = $client->__getLastRequest();
$lastResponse = $client->__getLastResponse();

Log these to inspect raw SOAP traffic (useful for WSDL mismatches).

Validate WSDL
- Use online tools (e.g., WSDL Analyzer) to verify the WSDL structure.
Check PHP SOAP Extensions
- Ensure the soap extension is enabled in php.ini:
```
extension=soap
```

Extension Points

Custom Response Handling

Override the client to transform responses:

class CustomSoapClient extends \Comsave\SoapClient\Client {
    public function __soapCall($functionName, $args) {
        $response = parent::__soapCall($functionName, $args);
        return $this->transformResponse($response);
    }

    protected function transformResponse($response) {
        // Custom logic (e.g., flatten arrays, cast types)
        return $response;
    }
}

Middleware for Requests

Intercept requests to modify payloads or headers:

$client->setMiddleware(function ($request) {
    $request->headers['X-Custom'] = 'value';
    return $request;
});

Laravel Events

Dispatch events before/after SOAP calls:

$client->beforeCall(function ($method, $params) {
    event(new SoapCallStarted($method, $params));
});

Soap Client Laravel Package