Soap Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require besimple/soap
   

   For Symfony projects, add besimple/soap-bundle to composer.json:

   "require": {
       "besimple/soap-bundle": "^0.2"
   }
   

2. First Use Case (Client):

   use BeSimple\SoapClient\SoapClient;
   
   $client = new SoapClient('http://example.com/service?wsdl', [
       'trace' => 1,
       'exceptions' => true,
   ]);
   $result = $client->someMethod(['param1' => 'value']);
   

3. First Use Case (Server):

   use BeSimple\SoapServer\SoapServer;
   use BeSimple\SoapWsdl\Wsdl;
   
   $wsdl = new Wsdl('http://example.com/schema.xsd');
   $wsdl->addMethod('someMethod', 'http://example.com/namespace', 'string', 'string');
   $server = new SoapServer($wsdl, ['trace' => 1]);
   $server->handle();
   

4. Key Files to Review:

   • src/BeSimple/SoapClient/README.md (for client-side usage)
   • src/BeSimple/SoapServer/README.md (for server-side setup)
   • src/BeSimple/SoapWsdl/README.md (for WSDL generation)

Implementation Patterns

Client-Side Workflows

1. Service Consumption:

   $client = new SoapClient('service.wsdl', [
       'features' => SoapClient::FEATURE_MTOM, // Enable MTOM for binary data
       'wsdl_cache' => '/tmp/wsdl_cache',      // Cache WSDL
   ]);
   $response = $client->__soapCall('methodName', [$args]);
   

2. Handling Complex Types:

   $client = new SoapClient('service.wsdl');
   $complexObject = new \stdClass();
   $complexObject->field1 = 'value1';
   $complexObject->field2 = 'value2';
   $result = $client->methodAcceptingComplexType($complexObject);
   

3. Error Handling:

   try {
       $client->__soapCall('methodName', [$args]);
   } catch (\SoapFault $fault) {
       \Log::error('SOAP Error: ' . $fault->getMessage());
       throw new \RuntimeException('SOAP request failed', 0, $fault);
   }
   

4. Logging and Debugging:

   $client = new SoapClient('service.wsdl', ['trace' => 1]);
   $client->__soapCall('methodName', [$args]);
   $request = $client->__getLastRequest();
   $response = $client->__getLastResponse();
   \Log::debug("Request: " . $request);
   \Log::debug("Response: " . $response);
   

Server-Side Workflows

1. Basic Server Setup:

   use BeSimple\SoapServer\SoapServer;
   use BeSimple\SoapWsdl\Wsdl;
   
   $wsdl = new Wsdl('http://example.com/schema.xsd');
   $wsdl->addMethod('getData', 'http://example.com/namespace', 'string', 'string');
   $server = new SoapServer($wsdl, [
       'classmap' => ['MyClass' => 'App\\Model\\MyClass'],
   ]);
   $server->handle();
   

2. Handling Requests:

   $server = new SoapServer($wsdl);
   $server->setClass('MyServiceClass'); // Bind to a class
   $server->handle();
   

3. Custom Logic:

   class MyServiceClass {
       public function getData($input) {
           // Custom logic
           return ['result' => $input . '_processed'];
       }
   }
   

4. WS-Security Integration:

   $server = new SoapServer($wsdl, [
       'wsSecurity' => [
           'username' => 'admin',
           'password' => 'secret',
       ],
   ]);
   

Integration Tips

1. Laravel Integration:

   • Use the besimple/soap-bundle for Symfony-like integration in Laravel.
   • For standalone use, bind the SoapClient/SoapServer to the Laravel container:

     $app->bind('soap.client', function ($app) {
         return new SoapClient('service.wsdl', ['trace' => 1]);
     });
     

2. Middleware for SOAP:

   // Example middleware to log SOAP requests
   $app->middleware(function ($request, $next) {
       if ($request->isSoap()) {
           \Log::info('SOAP Request: ' . $request->getContent());
       }
       return $next($request);
   });
   

3. Testing:

   • Use Mockery to mock SOAP responses in tests:

     $mock = Mockery::mock('overload:BeSimple\SoapClient\SoapClient');
     $mock->shouldReceive('__soapCall')->andReturn(['success' => true]);
     

Gotchas and Tips

Pitfalls

1. WSDL Caching:

   • Disable caching during development ('wsdl_cache' => null) to avoid stale WSDL issues.
   • Ensure the cache directory is writable.

2. Namespace Conflicts:

   • SOAP namespaces must match exactly between client and server. Use fully qualified names:

     $wsdl->addMethod('method', 'http://example.com/namespace/v1', 'string', 'string');
     

3. MTOM/SwA Limitations:

   • MTOM/SwA may not work with all PHP configurations. Ensure php-soap and php-xml extensions are enabled.
   • For large files, test with SoapClient::FEATURE_MTOM and adjust upload_max_filesize in php.ini.

4. WS-Security:

   • WS-Security requires phpseclib (composer require phpseclib/phpseclib). Add to composer.json:

     "require": {
         "phpseclib/phpseclib": "^2.0"
     }
     

5. Complex Types:

   • Avoid using PHP arrays directly for complex types. Use stdClass or custom objects with @soap annotations:

     /**
      * @soap
      */
     class MyComplexType {
         public $field1;
         public $field2;
     }
     

Debugging

1. Enable Traces:

   $client = new SoapClient('service.wsdl', ['trace' => 1]);
   // After call:
   \Log::debug("Request: " . $client->__getLastRequest());
   \Log::debug("Response: " . $client->__getLastResponse());
   

2. Check Headers:

   • SOAP faults often include headers. Inspect $fault->getMessage() and $fault->getDetail().

3. Validate WSDL:

   • Use online tools like WSDL Analyzer to validate your WSDL.

Configuration Quirks

1. SoapClient Options:

   • exceptions: Set to true to throw SoapFault exceptions instead of returning false.
   • location: Override the service endpoint URL.
   • uri: Override the target namespace.

2. SoapServer Options:

   • classmap: Map XML types to PHP classes (e.g., ['MyType' => 'App\\Model\\MyType']).
   • persistent: Use persistent connections (rarely needed).

3. WS-Security:

   • Ensure the wsSecurity option is an array:

     'wsSecurity' => [
         'username' => 'user',
         'password' => 'pass',
         'signature' => true, // Optional
     ]
     

Extension Points

1. Custom SoapClient: Extend BeSimple\SoapClient\SoapClient to add custom logic:

   class CustomSoapClient extends SoapClient {
       public function __construct($wsdl, $options = []) {
           parent::__construct($wsdl, $options);
           $this->addCustomHeader();
       }
   
       private function addCustomHeader() {
           $this->__setCookie('custom_token', 'abc123');
       }
   }
   

2. WSDL Generators: Use BeSimple\SoapWsdl\Wsdl to dynamically generate WSDL:

   $wsdl = new Wsdl('http://example.com/schema.xsd');
   $wsdl->addMethod('dynamicMethod', 'http://example.com/namespace', 'string',