Soap Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require splash/soap
   

   Register the bundle in config/app.php under providers:

   BadPixxel\SoapBundle\SoapBundle::class,
   

2. Basic Configuration Publish the default config (if available) and update config/soap.php:

   php artisan vendor:publish --provider="BadPixxel\SoapBundle\SoapBundle" --tag="config"
   

   Configure your SOAP endpoint, WSDL, and client options:

   'clients' => [
       'default' => [
           'wsdl' => 'http://example.com/service?wsdl',
           'options' => [
               'trace' => 1,
               'exceptions' => true,
           ],
       ],
   ],
   

3. First SOAP Call Inject the SoapClient via Laravel’s service container:

   use BadPixxel\SoapBundle\Service\SoapService;
   
   public function __construct(private SoapService $soapService) {}
   
   public function callSoapService()
   {
       $client = $this->soapService->getClient('default');
       $response = $client->someMethod(['param1' => 'value1']);
       return $response;
   }
   

Implementation Patterns

Workflow: SOAP Integration in Controllers/Jobs

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

   namespace App\Services;
   
   use BadPixxel\SoapBundle\Service\SoapService;
   
   class ExternalApiService {
       public function __construct(private SoapService $soapService) {}
   
       public function fetchUserData(int $userId): array
       {
           $client = $this->soapService->getClient('user_service');
           return $client->getUserById(['id' => $userId]);
       }
   }
   

2. Error Handling Centralize SOAP error handling in a middleware or decorator:

   try {
       $response = $this->soapService->call('default', 'method', [$param]);
   } catch (\SoapFault $fault) {
       Log::error("SOAP Error: {$fault->getMessage()}");
       throw new \RuntimeException("External API failed", 500);
   }
   

3. Dynamic Client Configuration Override client settings per request (e.g., for testing):

   $client = $this->soapService->getClient('default', [
       'options' => ['trace' => 1, 'exceptions' => false],
   ]);
   

4. Caching Responses Cache SOAP responses to reduce latency (e.g., using Laravel’s cache):

   $cacheKey = "soap_user_{$userId}";
   return Cache::remember($cacheKey, now()->addHours(1), function () use ($userId) {
       return $this->fetchUserData($userId);
   });
   

Gotchas and Tips

Pitfalls

1. WSDL Caching Issues

   • Problem: PHP’s SoapClient caches WSDLs aggressively, causing stale schemas.
   • Fix: Disable caching in options or clear cache manually:

     'options' => ['cache_wsdl' => WSDL_CACHE_NONE],
     

     Or use SoapClient::resetCache().

2. Namespace Collisions

   • Problem: SOAP responses may return objects with ambiguous namespaces (e.g., stdClass with conflicting properties).
   • Fix: Cast responses to arrays explicitly:

     $data = (array) $response->someMethod();
     

3. Timeouts and Large Payloads

   • Problem: SOAP calls may time out or fail with large payloads.
   • Fix: Adjust connection_timeout and local_cert in client options:

     'options' => [
         'connection_timeout' => 30,
         'stream_context' => stream_context_create([
             'ssl' => ['verify_peer' => false], // For testing only!
         ]),
     ],
     

4. Laravel Service Container Conflicts

   • Problem: The bundle may not bind SoapClient instances properly, leading to singleton issues.
   • Fix: Manually bind clients in a service provider:

     $this->app->bind('soap.client.default', function ($app) {
         return new \SoapClient(
             $app['config']['soap.clients.default.wsdl'],
             $app['config']['soap.clients.default.options']
         );
     });
     

Tips

1. Logging SOAP Requests/Responses Enable trace in options and log raw data:

   'options' => ['trace' => 1],
   

   Access traces via:

   $request = $client->__getLastRequest();
   $response = $client->__getLastResponse();
   

2. Testing SOAP Services Use mocks in PHPUnit to stub SOAP calls:

   $mock = $this->getMockBuilder(\SoapClient::class)
       ->disableOriginalConstructor()
       ->onlyMethods(['someMethod'])
       ->getMock();
   
   $mock->method('someMethod')->willReturn(['mocked' => 'data']);
   

3. Extending the Bundle

   • Override the SoapService to add custom logic (e.g., retry logic, headers):

     namespace App\Services;
     
     use BadPixxel\SoapBundle\Service\SoapService as BaseSoapService;
     
     class CustomSoapService extends BaseSoapService {
         public function call($clientName, $method, $params, $retries = 3) {
             // Custom retry logic here
             return parent::call($clientName, $method, $params);
         }
     }
     

   • Bind your custom service in AppServiceProvider:

     $this->app->bind(\BadPixxel\SoapBundle\Service\SoapService::class, App\Services\CustomSoapService::class);
     

4. Security Considerations

   • Validate all SOAP responses (e.g., check for required fields).
   • Avoid enabling exceptions => false in production (use middleware to handle faults).
   • Sanitize input parameters to prevent SOAP injection.