Soap Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require davefx/soap-bundle
   

   Register the bundle in config/bundles.php (Symfony 4+):

   return [
       // ...
       Davefx\SoapBundle\DavefxSoapBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan vendor:publish --tag=soap-bundle-config
   

   Edit config/soap.php to define your SOAP client(s):

   return [
       'clients' => [
           'example' => [
               'wsdl' => 'http://example.com/soap?wsdl',
               'options' => [
                   'trace' => true,
                   'exceptions' => true,
               ],
           ],
       ],
   ];
   

3. First SOAP Call Inject the SoapClientManager into a service/controller:

   use Davefx\SoapBundle\Manager\SoapClientManager;
   
   public function __construct(private SoapClientManager $soapManager) {}
   
   public function callExampleService()
   {
       $client = $this->soapManager->getClient('example');
       $response = $client->__soapCall('MethodName', [
           new \SoapParam('param1', 'value1'),
       ]);
       return $response;
   }
   

Implementation Patterns

Common Workflows

1. Service Layer Abstraction Create a dedicated service class to encapsulate SOAP logic:

   namespace App\Services;
   
   use Davefx\SoapBundle\Manager\SoapClientManager;
   
   class ExampleSoapService
   {
       public function __construct(private SoapClientManager $soapManager) {}
   
       public function getUserData(int $userId): array
       {
           $client = $this->soapManager->getClient('example');
           $response = $client->__soapCall('GetUserData', [
               new \SoapParam('userId', $userId),
           ]);
           return $this->mapResponse($response);
       }
   
       private function mapResponse($raw): array { /* ... */ }
   }
   

2. Request/Response Transformers Use decorators or middleware to transform requests/responses:

   // Example: Add auth headers to every SOAP call
   $client = $this->soapManager->getClient('example');
   $client->__setLocation('http://example.com/soap');
   $client->__setCookie('auth_token', 'xyz123');
   

3. Error Handling Centralize error handling in a base service:

   try {
       $response = $client->__soapCall('MethodName', $params);
   } catch (\SoapFault $fault) {
       throw new \RuntimeException(
           "SOAP Error: [{$fault->faultcode}] {$fault->faultstring}",
           0,
           $fault
       );
   }
   

4. Dynamic Client Configuration Override client options per request:

   $client = $this->soapManager->getClient('example', [
       'options' => [
           'trace' => true,
           'exceptions' => false,
       ],
   ]);
   

Gotchas and Tips

Pitfalls

1. WSDL Caching

   • Disable caching during development ('cache_wsdl' => WSDL_CACHE_NONE in options) to avoid stale schemas.
   • Clear cache manually if WSDL changes:

     $client->__setLocation('http://example.com/soap?wsdl=force');
     

2. SoapFault Ambiguity

   • SoapFault exceptions lack context. Log raw fault details:

     catch (\SoapFault $fault) {
         \Log::error('SOAP Fault', [
             'code' => $fault->faultcode,
             'string' => $fault->faultstring,
             'trace' => $fault->getTraceAsString(),
         ]);
     }
     

3. Namespace Collisions

   • SOAP responses may return objects with reserved PHP keywords (e.g., class). Cast to arrays:

     $response = (array) $client->__soapCall('MethodName', $params);
     

4. Performance

   • Reuse SoapClient instances (managed by the bundle) instead of creating new ones per request.
   • Avoid __doRequest() for simple calls; prefer __soapCall().

Tips

1. Debugging Enable tracing to inspect raw SOAP requests/responses:

   $client->setUseCurl(true); // For cURL debugging
   $response = $client->__soapCall('MethodName', $params);
   \Log::debug('SOAP Request', ['request' => $client->__getLastRequest()]);
   \Log::debug('SOAP Response', ['response' => $client->__getLastResponse()]);
   

2. Testing Mock the SoapClientManager in PHPUnit:

   $mockManager = $this->createMock(SoapClientManager::class);
   $mockManager->method('getClient')
       ->willReturn($this->createMock(\SoapClient::class));
   $this->instance(SoapClientManager::class, $mockManager);
   

3. Extension Points

   • Custom Clients: Register additional clients dynamically:

     $this->soapManager->addClient('dynamic', 'http://dynamic.com/soap?wsdl', []);
     

   • Event Listeners: Extend the bundle by subscribing to soap.client.created events (if supported in future versions).

4. Configuration

   • Use environment variables for sensitive WSDL URLs:

     'wsdl' => env('SOAP_EXAMPLE_WSDL', 'http://default.com/soap'),
     

   • Validate WSDL URLs early in bootstrap (e.g., via AppServiceProvider).