Nusoap Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require econea/nusoap
   

   • Node: v0.10.0 requires PHP >= 8.2. If you are still on PHP 8.1 or older, pin to the previous line instead:

     composer require "econea/nusoap:^0.9.20"
     

   • 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: The examples/ directory now includes dedicated server examples added in v0.10.0 — the fastest way to see a working Server + WSDL round-trip.
   • Tests: v0.10.0 reorganised the suite after contributte/doctrine-orm and added E2E server tests (Toolkit::test()). The server tests are the best reference for expected request/response shapes.
   • Release Notes: Review v0.10.0 — primarily a modernisation release: PHP 8.2 baseline, PHP 8.5 deprecation fixes, and a new configurable charencoding property.

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,  // Surface undefined output message warnings
       ]
   );
   

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

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

Controlling Character Encoding (new in v0.10.0)

Legacy SOAP services frequently expect ISO-8859-1 rather than UTF-8. The charencoding property is now configurable rather than hard-coded:

$client = new Client($wsdlUrl);

// Getter/setter added in #144
$client->setCharencoding('ISO-8859-1');
$previous = $client->getCharencoding(); // 'UTF-8' by default

This removes the need for the previous hack of mutating the property reflectively or subclassing. Set it before the first call() so it is applied during WSDL parsing and envelope serialisation.

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'],
       ]
   );
   

4. Server-side Encoding

   $server = new Server('https://example.com/soap-service.wsdl');
   $server->setCharencoding('ISO-8859-1'); // match the client/contract
   $server->register('GetUserData');
   $server->handle();
   

Integration Tips

• Laravel Service Providers Bind the client to the container for dependency injection, and expose the encoding as config:

  $this->app->bind(Client::class, function ($app) {
      $client = new Client(config('services.soap.endpoint'), [
          'trace' => $app['config']['services.soap.trace'],
          'strict_warnings' => true,
      ]);
  
      $client->setCharencoding($app['config']['services.soap.encoding'] ?? 'UTF-8');
  
      return $client;
  });
  

  Add SOAP_ENCODING to config/services.php so per-integration encoding is environment-driven — this is the single most useful new knob in v0.10.0.

• 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 parsed WSDL to avoid repeated network calls. Note that encoding now affects serialisation, so key the cache on it:

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

• Upgrading from 0.9.x Bump the PHP constraint in composer.json ("php": "^8.2") and run your SOAP integration tests. The 0.9.x code paths that emitted PHP 8.5 deprecations are fixed, so the upgrade is a net reduction in noise — but confirm your CI images are 8.2+ before merging.

Gotchas and Tips

Pitfalls

1. PHP 8.2 Minimum (Breaking in v0.10.0)

   • composer.json was modernised and now requires PHP >= 8.2. Installs on 8.1 and below will fail resolution rather than warn.
   • Fix: Pin "econea/nusoap": "^0.9.20" on older runtimes, or upgrade PHP. Note that the linter/test CI now only covers PHP 8.2–8.5, so 5.6–8.1 is no longer verified by the maintainers even though the code may still run.

2. Encoding Mismatch Between Client and Server

   • charencoding defaults to UTF-8. A service publishing ISO-8859-1 will produce mojibake or schema validation faults on accented characters.
   • Fix: Set the same encoding on both ends and assert on it in tests:

     $client->setCharencoding('ISO-8859-1');
     // ...
     $server->setCharencoding('ISO-8859-1');
     

3. Namespace Conflicts

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

     use Econea\NuSoap\Client as NuSoapClient;
     

4. WSDL Generation Issues

   • Auto-generated WSDLs may not match the expected schema. The static-vs-instance wsdl::$schemaTargetNamespace deprecation warning on PHP 8.2+ was fixed in v0.10.0, but custom overrides still need care.
   • Fix: Manually define complex types or extend the Server class:

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

5. Large Payloads

   • SOAP requests/responses with large payloads may hit PHP limits (post_max_size, memory_limit).
   • Fix: Raise limits or stream large data via cURL:

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

6. Fault Handling

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

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

7. Legacy Superglobals Removed

   • $HTTP_SERVER_VARS was removed in v0.10.0. Any custom subclass or copied-from-old-NuSOAP snippet referencing it will break.
   • Fix: Use $_SERVER directly, or better, inject request data instead of reading globals.

8. Undefined Output Messages

   • Still handled via strict_warnings; v0.10.0 additionally fixed the unrelated $tt_ns undefined-variable warning in serialize_val(), which previously polluted debug output.
   • Fix: new Client($wsdlUrl, ['strict_warnings' => true]) and define all output parameters in the WSDL.

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 XML — this is the fastest way to spot an encoding problem (look at the XML declaration's encoding= attribute).

2. Logging

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

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.
   • Character corruption: Verify getCharencoding() on both ends before blaming the payload.

4. Deprecation Noise (PHP 8.2–8.5)

   • v0.10.0 fixed the curl_close(), non-canonical cast, and wsdl::$schemaTargetNamespace deprecations. If you still see these after upgrading, you are almost certainly autoloading a stale copy or a second NuSOAP fork — run composer show econea/nusoap and composer why-not econea/nusoap 0.10.0.
   • Fix: Capture deprecations in CI (error_reporting(E_ALL)) so they do not accumulate silently.

Extension Points

1. Custom Fault Handling

   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. Client Request/Response Interception

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

   Verify these hook names against src/Econea/NuSoap/Client.php on the version you install — this surface is not covered by the 0.10.0 release notes.

3. Custom Transport Layer

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

4. Encoding-aware Subclass Where you cannot reach the client instance (e.g. deep inside a legacy service class), a thin subclass that applies encoding in the constructor keeps the concern in one place:

   class Latin1Client extends \Econea\NuSoap\Client
   {
       public function __construct(string $wsdl, array $options = [])
       {
           parent::__construct($wsdl, $options);
           $this->setCharencoding('ISO-8859-1');
       }
   }
   

5. Testing Use Laravel's HTTP fakes to stub SOAP responses, and lean on the new upstream E2E server tests as a reference for realistic envelopes:

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