Soap Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require codemitte/soap
   

2. Basic Client Initialization Create a SOAP client instance in your Laravel service or controller:

   use Codemitte\Soap\Client;
   
   $client = new Client('http://example.com/soap-service?wsdl');
   

3. First SOAP Call Invoke a simple SOAP method:

   $response = $client->__soapCall('MethodName', [
       'param1' => 'value1',
       'param2' => 'value2'
   ]);
   

4. Laravel Service Provider (Optional) Bind the client to Laravel’s container for dependency injection:

   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->singleton(Client::class, function ($app) {
           return new Client(config('soap.endpoint'));
       });
   }
   

5. Configuration Define SOAP endpoints in config/services.php:

   'soap' => [
       'endpoint' => 'http://example.com/soap-service?wsdl',
       'timeout' => 30,
       'trace' => true, // Enable for debugging
   ],
   

Implementation Patterns

Workflow: SOAP API Integration

1. Request Preparation Use Laravel’s request handling to map HTTP requests to SOAP calls:

   public function store(Request $request)
   {
       $client = app(Client::class);
       $response = $client->__soapCall('createOrder', $request->validate([
           'customerId' => 'required',
           'items' => 'required|array',
       ]));
   }
   

2. Response Handling Parse SOAP responses with Laravel’s response helpers:

   $data = json_decode(json_encode($response), true);
   return response()->json($data);
   

3. Error Handling Wrap SOAP calls in try-catch blocks:

   try {
       $response = $client->__soapCall('getUser', ['id' => 1]);
   } catch (\SoapFault $e) {
       Log::error('SOAP Error: ' . $e->getMessage());
       return response()->json(['error' => 'Service unavailable'], 500);
   }
   

Integration Tips

• Laravel Facades Create a facade for cleaner syntax:

  // app/Facades/SoapFacade.php
  public static function call($method, $params)
  {
      return app(Client::class)->__soapCall($method, $params);
  }
  

  Usage:

  $result = SoapFacade::call('getProduct', ['id' => 123]);
  

• Caching WSDL Cache the WSDL file to avoid repeated downloads:

  $client = new Client('http://example.com/wsdl');
  $client->setUseCurl(true); // Improve performance for large WSDLs
  

• Logging Enable trace logging for debugging:

  $client->setTrace(true);
  $client->__soapCall('method', []);
  $trace = $client->getLastRequestHeaders() . $client->getLastRequest();
  Log::debug('SOAP Request:', ['trace' => $trace]);
  

Gotchas and Tips

Pitfalls

1. SOAP Fault Handling

   • Issue: Generic SoapFault exceptions lack context.
   • Fix: Extend the client to include custom error messages:

     try {
         $response = $client->__soapCall('method', []);
     } catch (\SoapFault $e) {
         throw new \RuntimeException("SOAP Error: {$e->getMessage()} (Code: {$e->faultcode})");
     }
     

2. Namespace Conflicts

   • Issue: SOAP responses may use reserved PHP keywords (e.g., class).
   • Fix: Use json_decode with JSON_OBJECT_AS_ARRAY:

     $data = json_decode(json_encode($response), true);
     

3. Performance with Large Payloads

   • Issue: Default PHP SOAP client may timeout or fail with large requests.
   • Fix: Configure timeouts and use cURL:

     $client = new Client('http://example.com/wsdl');
     $client->setUseCurl(true);
     $client->setOptions(['timeout' => 60]);
     

4. WSDL Caching

   • Issue: WSDL files may change, causing stale cache issues.
   • Fix: Disable caching during development:

     $client->setCacheWsdl(false);
     

Debugging Tips

• Enable Trace Use setTrace(true) to inspect raw SOAP requests/responses:

  $client->setTrace(true);
  $client->__soapCall('method', []);
  var_dump($client->getLastRequestHeaders());
  var_dump($client->getLastRequest());
  

• Validate XML Use SimpleXMLElement to validate SOAP responses:

  $xml = new SimpleXMLElement($client->getLastResponse());
  if ($xml->getName() !== 'ExpectedRoot') {
      throw new \RuntimeException('Invalid SOAP response structure');
  }
  

Extension Points

1. Custom Headers Add SOAP headers for authentication:

   $header = new \SoapHeader('http://example.com/ns', 'AuthHeader', ['token' => 'abc123']);
   $client->__setSoapHeaders([$header]);
   

2. Middleware for SOAP Create middleware to preprocess SOAP requests:

   // app/Http/Middleware/SoapAuthMiddleware.php
   public function handle($request, Closure $next)
   {
       $client = app(Client::class);
       $client->__setSoapHeaders([new \SoapHeader('...', 'Auth', ['token' => auth()->token()])]);
       return $next($request);
   }
   

3. Queue SOAP Jobs Offload long-running SOAP calls to Laravel queues:

   dispatch(new SoapJob($client, 'processOrder', ['orderId' => 123]));
   

   // app/Jobs/SoapJob.php
   public function handle()
   {
       $this->client->__soapCall($this->method, $this->params);
   }