Nusoap Laravel Package

Technical Evaluation

Release Delta (v0.9.20 → v0.10.0) — this release is breaking for PHP < 8.2 and materially changes the maintenance profile. The previous assessment's core conclusion (SOAP is a deliberate, contained liability) holds, but three things shift: the supported-platform floor, the encoding capability for legacy endpoints, and the upstream quality signals (first real test suite + QA toolchain).

Architecture Fit

• Legacy SOAP Integration: contributte/nusoap v0.10.0 remains a NuSOAP fork targeting SOAP-based integrations with legacy systems (banks, government APIs, enterprise ERP/CRM). The architectural position is unchanged:
  • Use Cases: Legacy system migration, hybrid architectures, compliance-mandated SOAP.
  • Misalignment Risks (unchanged):
    • SOAP Overhead: Verbose, slow, no OpenAPI-style tooling. Prefer REST/gRPC/GraphQL where the counterparty allows it.
    • Stateful Complexity: WS-* standards add operational friction.
• v0.10.0 Impact — Breaking Platform Floor:
  • Require PHP >= 8.2 (a1e2167) drops PHP 5.6–8.1. This is the single decision-relevant change: it silently removes any Laravel service still on PHP 8.0/8.1 from the upgrade path.
  • New capability — configurable charencoding (#144): getter/setter for request/response character encoding. This is an architecture-relevant improvement for legacy counterparts using ISO-8859-1 / Windows-1252, and typically lets teams delete hand-rolled utf8_encode/utf8_decode shims at the integration boundary.
  • PHP 8.5 forward-compatibility: curl_close() deprecation, non-canonical cast deprecations, and wsdl::$schemaTargetNamespace (PHP 8.2+) fixed. Reduces runtime log noise but does not change design.

Integration Feasibility

• Laravel Compatibility — now version-gated by PHP, not by Laravel:

  Laravel	PHP Requirement	v0.10.0 Viable?
  9.x	8.0+	No (unless runtime is 8.2+)
  10.x	8.1+	Conditional — only where the runtime is 8.2+
  11.x / 12.x	8.2+	Yes

  • Manual Setup Still Required: no native Laravel integration. Wrap in a facade or container binding as before.
  • Dependency Conflicts: unchanged PHP extension requirements (soap, dom, xml). But Composer will now hard-fail on PHP < 8.2 at install time — a deterministic, pre-deploy failure rather than a runtime surprise.
• Example Integration (updated for charencoding):

  $client = new \nusoap_client('https://legacy-api.example.com/soap', 'wsdl');
  $client->setCharEncoding('ISO-8859-1'); // v0.10.0 — replaces manual transcoding shims
  try {
      $response = $client->call('LegacyMethod', ['param1' => 'value']);
      if ($client->fault) {
          throw new \RuntimeException($client->faultstring);
      }
  } catch (\nusoap_fault $fault) {
      throw new \RuntimeException("SOAP Fault: {$fault->faultstring}");
  }
  

Technical Risk

Key Questions

1. What is our runtime floor?
   • New: Inventory every Laravel service that could consume this package. Any on PHP 8.0/8.1 blocks ^0.10.0 and must stay pinned at ^0.9.20 — decide whether that's a temporary pin or an upgrade trigger.
2. Why SOAP?
   • Unchanged: Confirm whether SOAP is a one-time or long-term dependency; explore REST/gRPC where the counterparty permits.
3. Do any legacy endpoints use non-UTF-8 charsets?
   • New: If yes, charencoding is the reason to take this upgrade — quantify which integrations currently rely on hand-rolled transcoding.
4. Is static analysis actually gating?
   • New: PHPStan/CodeSniffer are allowed to fail. Treat the green badge as test-suite evidence, not type-safety evidence.
5. Test coverage boundaries
   • Updated: New suite covers serialization, helpers, and E2E server flows. Confirm coverage for WS-Security, faults, and your specific encoding scenario.
6. Laravel-specific needs — unchanged: facade vs. container binding, error-logging integration, APM/monitoring of SOAP calls.

Integration Approach

Stack Fit

• PHP/Laravel Stack:
  • Works with: PHP 8.2–8.5, Laravel 11/12 natively; Laravel 10 only where the runtime is 8.2+.
  • Extensions Required: unchanged (soap, dom, xml).
  • Container binding (unchanged shape, new encoding control):

    // config/app.php
    'bindings' => [
        \App\Services\LegacySoapService::class => function ($app) {
            $client = new \nusoap_client('https://api.example.com/soap', 'wsdl');
            $client->setCharEncoding(config('services.legacy_soap.charencoding', 'UTF-8'));
            return new \App\Services\LegacySoapService($client);
        },
    ],
    

• Alternatives Considered (unchanged): fruitcake/laravel-soap or custom REST proxies remain viable if SOAP is avoidable.

Migration Path

1. Phase 0 — Platform Audit (new): Confirm the PHP runtime of every consuming service. This gates everything downstream.
2. Phase 1: PoC — Single endpoint. Exercise the PHP 8.2+/8.5 deprecation fixes and, where applicable, charencoding round-trip against a real non-UTF-8 payload.
3. Phase 2: Wrapper Layer — Service class encapsulates the client, exposes charencoding via config, normalizes faults to Laravel exceptions.
4. Phase 3: Observability — Log SOAP calls and faults; confirm the deprecation fixes actually reduced log volume.
5. Phase 4: Exit Strategy — Continue gradual replacement of SOAP where the counterparty supports it.

Compatibility

• PHP Version: 8.2–8.5 only. This is a hard floor. Composer refuses to resolve ^0.10.0 below 8.2 — fail fast, not at runtime.
• Laravel Version: 11/12 clean; 10 conditional; 9 blocked in practice.
• charencoding: new public API; safe additive change, but behavior changes if you set it — audit downstream string handling and DB column collations before enabling.
• Removed legacy artifacts: $HTTP_SERVER_VARS global and the undefined $tt_ns variable are gone. Both are dead-code cleanups with negligible regression surface, but worth a smoke test on any heavily customized fork.
• WS- Standards*: unchanged; test WS-Security if required.

Sequencing

1. Prerequisites: Enable PHP extensions; confirm PHP >= 8.2 across all consumers.
2. Core Implementation: Add/verify the container binding and charencoding config.
3. Integration: Expose via commands, queues, or routes (unchanged).
4. Observability: Baseline warning/notice volume pre-upgrade, then compare post-upgrade to validate the deprecation fixes.
5. Rollback: Keep ^0.9.20 pinned in a branch — it remains installable on PHP 8.0/8.1.

Operational Impact

Maintenance

• Dependency Management:
  • If runtime is PHP 8.2+: "contributte/nusoap": "^0.10.0".
  • If runtime is PHP 8.0/8.1: stay on "^0.9.20" and treat this as a tracked technical-debt item, not a silent pin.
• Upstream Health Improved: v0.10.0 adds a real test suite (contributte/tester), E2E server tests, PHPStan/CodeSniffer config, a Makefile QA toolchain, Codecov reporting, and CI on PHP 8.2–8.5. This is the first release where the "we may need to fork" contingency can reasonably be deferred.
• Caveats: tests run on 8.2–8.5 only while the linter matrix still spans 5.6–8.5; static analysis is explicitly non-blocking; multiple commits are AI-authored. Review diffs rather than assuming the green CI implies correctness.

Support

• Laravel Integration: still manual; document the binding and the charencoding config key for future developers.

  /**
   * @throws \RuntimeException If the SOAP call faults or returns an invalid payload.
   */
  public function callLegacySoap(): mixed
  

• Community Support: active maintenance with external contributors plus tooling investment — a genuine improvement over v0.9.20. Raise issues on the GitHub repo.

Scaling

• Performance: unchanged. SOAP remains the bottleneck; cache responses where semantics allow. Note that request/response transcoding for non-UTF-8 charsets adds marginal CPU cost — measure if payloads are large.
• Concurrency: unchanged; validate parallel SOAP calls under load, particularly once charencoding is enabled for a high-volume endpoint.

Failure Modes

Ramp-Up

• Onboarding:
  • Document three things: the PHP 8.2 floor, the charencoding config key, and the pin/upgrade decision for any service still on 8.1.
  • Example note:

    "v0.10.0 requires PHP >= 8.2. Services on 8.1 must remain on ^0.9.20. For legacy endpoints using non-UTF-8 charsets, set services.legacy_soap.charencoding."

• Training:
  • Teach teams to mock SOAP responses in tests; the upstream suite (contributte/tester + E2E server tests) is now a usable reference for fixture design.
  • Add a review checkpoint: verify encoding behavior whenever a new counterparty is onboarded.