Besimple Soap Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require awelara/besimple-soap-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Awelara\BeSimpleSoapBundle\AwelaraBeSimpleSoapBundle::class => ['all' => true],
   ];
   

2. First Use Case: Consuming a SOAP Service Define a client configuration in config/packages/besimple_soap.yaml:

   besimple_soap:
       clients:
           example_client:
               wsdl: "http://example.com/service?wsdl"
               options:
                   trace: true
                   exceptions: true
   

   Inject the client in a service:

   use Awelara\BeSimpleSoapBundle\Client\SoapClient;
   
   class ExampleService
   {
       public function __construct(private SoapClient $exampleClient) {}
   
       public function callService()
       {
           $result = $this->exampleClient->__soapCall('MethodName', ['arg1' => 'value']);
           return $result;
       }
   }
   

3. First Use Case: Exposing a SOAP Service Define a server configuration in config/packages/besimple_soap.yaml:

   besimple_soap:
       servers:
           example_server:
               uri: "/soap"
               class: "App\Service\SoapService"
               methods:
                   - "getData"
                   - "updateData"
   

   Implement the service class:

   class SoapService
   {
       public function getData($param) { /* ... */ }
       public function updateData($param) { /* ... */ }
   }
   

Implementation Patterns

Consuming SOAP Services

1. Dynamic Client Configuration Use dependency injection to create clients dynamically:

   $client = $container->get('besimple_soap.client.example_client');
   

2. Handling Complex Types Map complex types via annotations or XML schemas:

   use Awelara\BeSimpleSoapBundle\Annotation as Soap;
   
   class ComplexType
   {
       /**
        * @Soap\SoapType(name="complexType")
        */
       public $field;
   }
   

3. Asynchronous Requests Use Symfony’s Messenger component with the SOAP client:

   $message = new SoapCallMessage('MethodName', ['arg' => 'value']);
   $this->messageBus->dispatch($message);
   

Exposing SOAP Services

1. Method-Level Security Secure endpoints with Symfony’s security system:

   # config/packages/security.yaml
   access_control:
       - { path: ^/soap, roles: ROLE_SOAP_USER }
   

2. WSDL Generation Auto-generate WSDL dynamically:

   $wsdl = $this->container->get('besimple_soap.server.example_server')->getWsdl();
   

3. Integration with Symfony Forms Validate SOAP payloads using Symfony’s form system:

   $form = $this->createForm(SoapDataType::class, $data);
   if ($form->isSubmitted() && $form->isValid()) { /* ... */ }
   

Workflows

1. Request-Response Cycle

   • Request: Parse incoming SOAP XML, validate, and dispatch to service.
   • Response: Format service output into SOAP XML.
   • Logging: Log requests/responses via Symfony’s Monolog:

     besimple_soap:
         logging: true
     

2. Testing Use HttpClient to mock SOAP calls:

   $client = $this->createMock(SoapClient::class);
   $client->method('__soapCall')->willReturn(['mocked' => 'response']);
   $this->container->set('besimple_soap.client.example_client', $client);
   

Gotchas and Tips

Pitfalls

1. PHP SOAP Extension Quirks

   • Ensure ext-soap is enabled (php -m | grep soap).
   • Some WSDLs may require soap.wsdl_cache_enabled=0 in php.ini for dynamic services.

2. Namespace Conflicts SOAP namespaces must match exactly. Use fully qualified class names:

   namespace App\Soap\Types;
   class User { /* ... */ }
   

3. Large Payloads Increase soap.wsdl_cache and memory_limit for large WSDLs or payloads.

4. Symfony 4+ Compatibility

   • The bundle targets Symfony 4.1 but may need tweaks for newer versions (e.g., autowiring).
   • Override services if autowiring fails:

     # config/services.yaml
     Awelara\BeSimpleSoapBundle\Client\SoapClient: ~
     

Debugging

1. Enable SOAP Traces

   besimple_soap:
       clients:
           example_client:
               options:
                   trace: true
   

   Access traces via:

   $client->__getLastRequest();
   $client->__getLastResponse();
   

2. WSDL Validation Validate WSDLs using online tools (e.g., WSDL Analyzer) before integration.

3. Common Errors

   • SOAP-ERROR: Parsing WSDL: Check WSDL URL and XML syntax.
   • SOAP-ERROR: Encoding: Ensure types match (e.g., string vs. int).
   • Class not found: Verify namespace and annotation usage.

Tips

1. Reuse Clients Cache clients in services to avoid re-parsing WSDLs:

   private SoapClient $client;
   
   public function __construct(SoapClient $client) {
       $this->client = $client;
   }
   

2. Custom SOAP Headers Add headers dynamically:

   $header = new SoapHeader('namespace', 'headerData', ['key' => 'value']);
   $this->client->__setSoapHeaders([$header]);
   

3. Performance

   • Disable WSDL caching in development:

     besimple_soap:
         clients:
             example_client:
                 options:
                     wsdl_cache_enabled: false
     

   • Use curl for non-SOAP endpoints if possible (faster than SOAP).

4. Extending Functionality

   • Custom Serializers: Override besimple_soap.serializer to handle custom types.
   • Middleware: Add logic via event listeners (e.g., besimple_soap.client.event).
   • Docker: Use services.yaml to configure PHP SOAP settings:

     php:
         ini:
             soap.wsdl_cache_enabled: "0"