Soap Common Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require besimple/soap-common:0.2.*@dev
   

   Verify the package loads in config/app.php under providers.

2. First Use Case:

   • For SOAP Client: Use the SoapClient wrapper to handle MIME attachments (SwA/MTOM):

     use BeSimple\SoapCommon\SoapClient\SoapClient;
     use BeSimple\SoapCommon\SoapClient\SoapClientOptions;
     
     $options = new SoapClientOptions();
     $options->setWsdl('path/to/wsdl.wsdl');
     $options->setClassMap([...]); // Map complex types if needed
     
     $client = new SoapClient($options);
     $response = $client->__soapCall('methodName', [$arg1, $arg2]);
     

   • For SOAP Server: Extend BeSimple\SoapCommon\SoapServer\SoapServer to define endpoints:

     use BeSimple\SoapCommon\SoapServer\SoapServer;
     
     $server = new SoapServer('path/to/wsdl.wsdl', [
         'classmap' => [...],
         'uri' => 'http://example.com/soap'
     ]);
     $server->handle();
     

3. Key Files:

   • src/SoapClient/ and src/SoapServer/ for core logic.
   • src/TypeConverter/ for custom type handling.

Implementation Patterns

Workflows

1. Client-Side Workflow:

   • Request Handling: Use SoapClientOptions to configure:

     $options->setMimeType('multipart/related'); // For SwA/MTOM
     $options->setAttachments([...]); // Binary data (e.g., files)
     

   • Response Parsing: Access MIME parts via $response->getMimeParts() or raw XML with $response->getRawResponse().

2. Server-Side Workflow:

   • Endpoint Definition: Override SoapServer methods or use annotations (if supported) to map PHP methods to SOAP actions.
   • Attachment Handling: Retrieve attachments in handlers:

     $attachments = $request->getMimeParts();
     foreach ($attachments as $attachment) {
         $data = $attachment->getData();
     }
     

3. Type Conversion:

   • Register custom converters in SoapClientOptions:

     $options->addTypeConverter(new CustomTypeConverter());
     

   • Handle complex types via classmap:

     $options->setClassMap([
         'ns\ComplexType' => 'App\Models\ComplexTypeModel'
     ]);
     

Integration Tips

• Laravel Integration:
  • Bind the SoapClient to the container in AppServiceProvider:

    $this->app->bind(SoapClient::class, function ($app) {
        return new SoapClient(new SoapClientOptions());
    });
    

  • Use middleware to validate SOAP requests/responses.
• Testing:
  • Mock SoapClient/SoapServer in unit tests:

    $mockClient = Mockery::mock(SoapClient::class);
    $mockClient->shouldReceive('__soapCall')->andReturn($mockResponse);
    

Gotchas and Tips

Pitfalls

1. MIME Handling:

   • SwA vs. MTOM: Ensure the server/client supports the correct MIME type. SwA (multipart/related) is more widely supported but less efficient than MTOM (message/x-mtom).
   • Attachment Limits: Large attachments may hit PHP’s upload_max_filesize or post_max_size. Adjust in php.ini or stream attachments directly to storage.

2. Type Conversion:

   • Classmap Conflicts: Overlapping namespace/class names in classmap will cause silent failures. Validate mappings with:

     $options->validateClassMap();
     

   • Circular References: Complex type converters may loop infinitely. Use lazy loading or break cycles manually.

3. WSDL Caching:

   • Disable caching during development ($options->setCacheWsdl(false)) to avoid stale schemas.

Debugging

• Enable Logging:

  $options->setDebug(true); // Logs requests/responses to storage/logs/soap.log
  

• Raw XML Inspection: Dump raw SOAP envelopes for debugging:

  file_put_contents('debug.xml', $response->getRawResponse());
  

• Common Errors:
  • SOAP-ENV:Client: Validate WSDL URL and namespace URIs.
  • SOAP-ENV:Server: Check for missing method annotations or unregistered classmaps.

Extension Points

1. Custom MIME Parsers: Extend BeSimple\SoapCommon\Mime\MimeParser to support non-standard MIME formats.

2. Security:

   • Sanitize SOAP actions to prevent SSRF or DoS:

     $server->setAllowedActions(['ns:safeAction']);
     

   • Validate attachments for malicious content (e.g., PHP code in files).

3. Performance:

   • Streaming: For large responses, implement SoapResponseStream to avoid memory overload.
   • Batch Processing: Use SoapClient::setBatchMode(true) for bulk operations.

Config Quirks

• Namespace Handling: Ensure WSDL namespaces match PHP class namespaces. Use targetNamespace in WSDL or adjust classmap keys.
• Dev vs. Prod: Disable debug mode in production ($options->setDebug(false)) to avoid log exposure.