Soap Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require barm/soap-bundle
   

   Add to config/bundles.php (Symfony 4+):

   return [
       // ...
       Barm\Bundle\SoapBundle\BarmSoapBundle::class => ['all' => true],
   ];
   

2. First Use Case: Replace direct SoapClient instantiation with the bundle’s factory:

   use Symfony\Component\DependencyInjection\ContainerInterface;
   
   class MyService {
       public function __construct(private ContainerInterface $container) {}
   
       public function callSoapService() {
           $wsdl = 'https://example.com/service.wsdl';
           $soapClient = $this->container->get('barm_soap.factory')->create($wsdl);
           $result = $soapClient->__soapCall('MethodName', [$arg1, $arg2]);
           return $result;
       }
   }
   

3. Verify Profiler Integration: Check the WebProfiler toolbar under the "SOAP" tab to see logged requests.

Implementation Patterns

Dependency Injection Workflow

1. Service Configuration (Recommended): Define SOAP clients as services in config/services.yaml:

   services:
       App\Service\MySoapService:
           arguments:
               $soapClient: '@barm_soap.factory'
           calls:
               - [setWsdl, ['%env(WSDL_URL)%']]
   

2. Factory Method Pattern: Use the factory to create SoapClient instances dynamically:

   $client = $this->container->get('barm_soap.factory')->create($wsdl, [
       'trace' => 1,
       'exceptions' => true,
   ]);
   

3. Event Dispatching: Listen for soap.request events (triggered after each request) to log or transform responses:

   // src/EventListener/SoapListener.php
   class SoapListener {
       public function onSoapRequest(SoapRequestEvent $event) {
           $response = $event->getResponse();
           // Modify or log $response
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\SoapListener:
           tags: ['kernel.event_listener', { event: 'soap.request' }]
   

4. Configuration Overrides: Customize default options via config/packages/barm_soap.yaml:

   barm_soap:
       default_options:
           trace: 1
           cache_wsdl: WSDL_CACHE_BOTH
   

Gotchas and Tips

Pitfalls

1. Profiler Dependency:

   • The SOAP tab in WebProfiler will not appear if:
     • Debug mode is disabled (APP_DEBUG=false).
     • The webprofiler bundle is not installed (Symfony Flex includes it by default).
   • Fix: Ensure APP_DEBUG=1 in .env during development.

2. Event Dispatching Timing:

   • The soap.request event fires after the SOAP request completes, so it’s unsuitable for request-level modifications (e.g., headers).
   • Workaround: Use Symfony’s kernel.request event to pre-process SOAP calls if needed.

3. WSDL Caching:

   • Disabling cache_wsdl (e.g., WSDL_CACHE_NONE) may cause performance issues on repeated calls.
   • Tip: Use WSDL_CACHE_DISK for development and WSDL_CACHE_BOTH for production.

4. Factory vs. Direct Instantiation:

   • Avoid mixing the bundle’s factory with direct new SoapClient() calls—this breaks profiler logging.
   • Tip: Use the factory consistently across the application.

Debugging Tips

1. Enable SOAP Traces: Pass trace: 1 to the factory to log raw request/response data:

   $client = $factory->create($wsdl, ['trace' => 1]);
   $client->__soapCall(...);
   // Check $client->__getLastRequest() and $client->__getLastResponse()
   

2. Profiler Data:

   • Inspect the SOAP tab in WebProfiler for:
     • Request/response payloads.
     • Execution time.
     • Headers and faults.
   • Shortcut: Append ?_profiler=soap to your request URL.

3. Common SOAP Errors:

   • "SoapFault" exceptions: Check the faultstring and faultcode in the profiler.
   • Timeouts: Increase connection_timeout or receive_timeout in the factory options.

Extension Points

1. Custom Event Subscribers: Extend the SoapRequestEvent to add metadata or validate responses:

   class CustomSoapSubscriber implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return ['soap.request' => 'onSoapRequest'];
       }
   
       public function onSoapRequest(SoapRequestEvent $event) {
           $event->setMetadata(['custom_key' => 'value']);
       }
   }
   

2. Middleware for SOAP: Use Symfony’s HttpClient middleware to pre-process SOAP requests (e.g., add auth headers):

   $client = $factory->create($wsdl);
   $client->__setLocation('https://custom-endpoint.com');
   

3. Testing: Mock the factory in PHPUnit:

   $this->container->get('barm_soap.factory')->method('create')->willReturn($mockSoapClient);