Nusoap Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require econea/nusoap

• No additional configuration is required for basic usage.

2. First Use Case: SOAP Client

   use Econea\NuSoap\Client;
   
   $client = new Client('https://example.com/soap-service?wsdl');
   $response = $client->call('MethodName', ['param1' => 'value1']);
   print_r($response);
   

3. First Use Case: SOAP Server

   use Econea\NuSoap\Server;
   
   $server = new Server('https://example.com/soap-service.wsdl');
   $server->register('MethodName');
   $server->handle();
   

4. Where to Look First

   • Documentation: NuSOAP Official Docs (adapted for this fork).
   • Source Code: Focus on src/Econea/NuSoap/ for core classes like Client, Server, and Fault.
   • Examples: Check the examples/ directory in the repository (if available) for practical use cases.
   • Release Notes: Review v0.9.20 for the latest bug fixes, particularly the warning handling for undefined output messages.

Implementation Patterns

Common Workflows

SOAP Client Workflow

1. Instantiation

   $client = new Client(
       'https://example.com/soap-service?wsdl',
       [
           'trace' => 1, // Enable request/response logging
           'exceptions' => true, // Throw exceptions on errors
           'strict_warnings' => true, // Handle undefined output messages (new in v0.9.20)
       ]
   );
   

2. Calling Methods

   // Simple call
   $response = $client->call('GetData', ['id' => 123]);
   
   // Complex call with namespaces
   $response = $client->call(
       'ComplexMethod',
       ['param' => ['@attributes' => ['ns' => 'urn:namespace']]],
       ['namespace' => 'urn:namespace']
   );
   

3. Handling Responses

   if ($client->fault) {
       throw new \RuntimeException($client->faultstring);
   }
   $result = $client->getResponse();
   

4. Debugging

   // Enable debug output
   $client->setDebugLevel(9);
   echo '<pre>' . htmlspecialchars($client->getDebug(), ENT_QUOTES) . '</pre>';
   

SOAP Server Workflow

1. Registering Methods

   $server = new Server('https://example.com/soap-service.wsdl');
   $server->register('GetUserData');
   $server->register('UpdateUser', ['in' => 'userId', 'out' => 'userData']);
   

2. Handling Requests

   $server->setObject(new class {
       public function GetUserData($userId) {
           return ['id' => $userId, 'name' => 'John Doe'];
       }
   });
   

3. Custom WSDL Handling

   $server->wsdl->addComplexType(
       'UserData',
       'complexType',
       'struct',
       'sequence',
       [
           ['name' => 'id', 'type' => 'xsd:int'],
           ['name' => 'name', 'type' => 'xsd:string'],
       ]
   );
   

Integration Tips

• Laravel Service Providers Bind the client/server to the container for dependency injection:

  $this->app->bind(Client::class, function ($app) {
      return new Client(config('services.soap.endpoint'), [
          'trace' => $app['config']['services.soap.trace'],
          'strict_warnings' => true, // Leverage the new warning handling
      ]);
  });
  

• Middleware for SOAP Requests Use Laravel middleware to validate or transform SOAP requests before they reach the server:

  $server->register('SecureMethod', [], ['middleware' => 'validateSoapRequest']);
  

• Caching WSDL Cache the WSDL parsing result to avoid repeated network calls:

  $wsdlCache = Cache::remember('soap_wsdl_' . md5($wsdlUrl), 3600, function () use ($wsdlUrl) {
      return new Client($wsdlUrl, ['strict_warnings' => true]);
  });
  

Gotchas and Tips

Pitfalls

1. PHP Version Compatibility

   • Ensure your PHP version (5.6–8.5) matches the package’s supported range. Test on all target versions.
   • Fix: Use composer.json constraints or CI checks (e.g., GitHub Actions) to enforce version compatibility.

2. Namespace Conflicts

   • NuSOAP uses its own namespace handling, which may clash with Laravel’s or other packages.
   • Fix: Explicitly prefix NuSOAP classes:

     use Econea\NuSoap\Client as NuSoapClient;
     

3. WSDL Generation Issues

   • Auto-generated WSDLs may not match the expected schema.
   • Fix: Manually define complex types or extend the Server class to customize WSDL generation:

     $server->wsdl->schemaTargetNamespace = 'urn:custom-namespace';
     

4. Large Payloads

   • SOAP requests/responses with large payloads may hit PHP limits (e.g., post_max_size, memory_limit).
   • Fix: Increase limits in php.ini or stream large data:

     $client->setUseCurl(true);
     $client->setCurlOption(CURLOPT_TIMEOUT, 30);
     

5. Fault Handling

   • Faults may not always throw exceptions if exceptions is set to false.
   • Fix: Always check $client->fault after calls:

     if ($client->fault) {
         Log::error('SOAP Fault: ' . $client->faultstring);
         throw new \RuntimeException($client->faultstring, $client->faultcode);
     }
     

6. Undefined Output Messages (New in v0.9.20)

   • The package now handles warnings for undefined output messages more gracefully.
   • Fix: Enable strict_warnings in the client configuration to ensure warnings are caught:

     $client = new Client($wsdlUrl, ['strict_warnings' => true]);
     

Debugging Tips

1. Enable Full Debugging

   $client->setDebugLevel(9); // Max verbosity
   echo '<pre>' . htmlspecialchars($client->getDebug(), ENT_QUOTES) . '</pre>';
   

   • Check $client->getLastRequest() and $client->getLastResponse() for raw data.

2. Logging Use Laravel’s logging to persist debug info:

   Log::debug('SOAP Request', ['request' => $client->getLastRequest()]);
   

3. Common Errors

   • SOAP-ENV:Server: Server-side error. Check the server’s debug logs.
   • SOAP-ENV:VersionMismatch: WSDL or SOAP version mismatch. Verify the WSDL URL and SOAP version.
   • SOAP-ENV:Client: Client-side error (e.g., invalid parameters). Validate input data.
   • Undefined Output Messages: If using strict_warnings, ensure all output parameters are defined in the WSDL or method signature.

Extension Points

1. Custom Fault Handling Extend the Fault class to add custom logic:

   class CustomFault extends \Econea\NuSoap\Fault {
       public function __construct($faultcode, $faultstring, $faultactor = null) {
           parent::__construct($faultcode, $faultstring, $faultactor);
           // Add custom logic (e.g., logging, retries)
       }
   }
   

2. Middleware for Client Intercept requests/responses:

   $client->setMiddleware(function ($request, $response, $client) {
       // Pre-process request
       $request = str_replace('old', 'new', $request);
       return [$request, $response];
   });
   

3. Custom Transport Layer Replace the default HTTP transport (e.g., for Guzzle or custom HTTP clients):

   $client->setUseCurl(false);
   $client->setTransport(new CustomTransport());
   

4. Testing Use Laravel’s HTTP tests to mock SOAP responses:

   $response = Http::fake([
       'https://example.com/soap-service' => Http::response($mockXml, 200),
   ]);