Wse Php Laravel Package

Technical Evaluation

Architecture fit

• robrichards/wse-php is a low-level WS-Security plumbing library, not a Laravel package. It has no service provider, facade, config publishing, or container awareness. It decorates native ext/soap (SoapClient, SoapVar, SoapHeader) to add UsernameToken, Timestamp, BinarySecurityToken, and XML Digital Signature/Encryption via xmlseclibs.
• Fit is therefore "inside the boundary, not at the edge." It belongs behind an anti-corruption layer: a WsseSoapClient wrapper plus a factory resolved from the container, so application code never touches RobRichards\WsePhp\* classes directly.
• It is orthogonal to Laravel's HTTP client. Http::withHeaders() cannot produce WS-Security envelopes, so teams expecting to reuse existing Http retry/middleware/telemetry patterns will be disappointed — those must be reimplemented around a blocking SOAP call.
• Good architectural signal: the library is framework-agnostic and stateless per call, so it composes cleanly with jobs, actions, and queued integrations without fighting Laravel conventions.

Integration feasibility

• High. composer require robrichards/wse-php plus ext-soap and ext-openssl in the runtime image. No Laravel version constraints, no facade conflicts, no published assets. Typical effort for a first working signed request against a sandbox: 1–3 days.
• The real work is not the library — it is certificate handling (PEM/key pairs, passphrases, rotation), WSDL acquisition and caching, and environment-specific endpoint configuration. Budget accordingly.
• Works in both WSDL and non-WSDL mode; non-WSDL mode is often required by partners whose WSDL is broken or unavailable in lower environments.

Technical risk

• Low dependency risk, medium integration risk. The package is stable and slow-moving, which is good for churn and bad for responsiveness. 130 stars and a single-maintainer profile is a bus-factor concern for a dependency that may sit on a payment or compliance path; the code is MIT and small enough to vendor or fork if abandoned.
• Cryptographic correctness risk. WS-Security failures are silent and opaque: signature validation errors surface as generic SOAP faults. Canonicalization, namespace prefixes, and whitespace all matter. Default algorithm choices must be pinned explicitly (RSA-SHA256 / SHA-256, not SHA-1) — do not rely on defaults, and confirm what each counterparty accepts.
• Runtime risk under Octane/RoadRunner. SoapClient instances and any per-request key material must not be shared across requests; treat the client as request-scoped and never as a singleton with mutable signature state.
• Certificates and clock skew. Timestamp elements typically carry a 5-minute TTL. Container clock drift and short-lived certs are the two most common production incidents for this class of integration.
• Version marker ambiguity. The "last release" signal (dated in the future relative to typical data) suggests the maturity metric is unreliable; validate actual tag history and PHP 8.x compatibility from the repo, not from the score.

Key questions

1. Do we actually need WS-Security, or is the counterparty offering mTLS, OAuth2, or HMAC-signed REST? WS-Security is the most expensive option we can choose.
2. Which profiles are required: UsernameToken (plaintext vs digest), X.509 signature, Timestamp, encryption, WS-Addressing? Each adds test surface.
3. Which algorithm suite will the partner accept, and do they support SHA-256, or are we forced onto SHA-1 for legacy reasons?
4. How many partners/endpoints, and is each one bespoke? Volume drives whether this is one wrapper class or a small internal package.
5. What is the certificate lifecycle owner and rotation runbook? Where do private keys live — secrets manager, mounted volume, or .env?
6. Is ext-soap present in all target images (local, CI, staging, prod, and any FaaS/container runtime)?
7. What is the fallback if the maintainer disappears — vendor the source, fork, or replace with a commercial SOAP/WS-Security product?

Integration Approach

Stack fit

• Laravel 10/11/12 on PHP 8.1+ with ext-soap and ext-openssl enabled. No framework coupling, so it slots into any Laravel codebase without touching bootstrap/app.php or provider ordering.
• Natural placement: app/Integrations/{Partner}/ with a …Client that wraps WSSESoap, a …ClientFactory, a config/integrations/{partner}.php config file, and a queued Job per operation. This keeps SOAP mechanics out of controllers, Livewire components, and Filament resources.
• Do not try to route this through Laravel's Http client or Saloon. Saloon is a good fit for REST and a poor fit here; wrapping it adds abstraction without solving the envelope-signing problem.

Migration path

• Start with a throwaway artisan command or a single feature test that signs an envelope and prints it. Validate the XML against the partner's sandbox before writing any abstractions.
• Then formalize: config file for endpoint/WSDL/SOAP version/timeouts, secrets for keystore paths and passphrases, a factory bound to an interface, and a single call(string $operation, array $payload): array entry point that normalizes faults into domain exceptions.
• Replace any existing ad-hoc new SoapClient(...) scattered in controllers with the wrapper, one call site at a time. There is no schema or data migration; the migration is behavioral.

Compatibility

• Composer conflict surface is small; the transitive dependency is robrichards/xmlseclibs. Audit for a second copy pulled in by another package (composer why robrichards/xmlseclibs) and align versions.
• PHP 8.x deprecation noise (dynamic properties, implicit nullable) is the likeliest friction; if the tagged release predates your PHP version, test explicitly and be prepared to pin or patch.
• Coexists fine with Laravel's Http client, Guzzle, and any REST integrations in the same app; keep SOAP and REST clients separate in the directory structure so the distinction stays visible.

Sequencing

1. Spike (1–3 days): one signed request against partner sandbox; capture request/response envelopes as fixtures.
2. Configuration and secrets: config file, .env keys, secrets manager wiring, cert/key placement, .gitignore hygiene for PEMs.
3. Wrapper and exception mapping: WsseSoapClient, factory, SoapFault → typed exceptions, timeouts, WSDL cache settings.
4. Tests: fixture-based envelope assertions (signature presence, algorithm URIs, timestamp window) plus a fake transport for application-level tests so CI never calls the partner.
5. Observability: structured logs with correlation IDs, redacted envelope capture in non-prod only, metrics on latency and fault codes.
6. Rollout: queue-backed where the business allows async, feature-flagged call sites, then decommission any legacy SOAP path.

Operational Impact

Maintenance

• Low ongoing code maintenance — the library is small, stable, and rarely changes. The recurring cost is configuration maintenance: certificates, endpoints, partner-side changes, and WSDL drift.
• Budget an explicit certificate-expiry calendar and alerting (30/14/7 days). This is the single highest-value operational control for this dependency.
• Consider vendoring or a thin internal fork under MIT if the upstream goes quiet, so a PHP 9 or xmlseclibs security patch is not blocked on a single maintainer.

Support

• Community-only support: GitHub issues, no SLA, no commercial backing. Acceptable for a stable internal integration; risky if a payment or regulatory flow depends on it and the team has no SOAP/crypto depth.
• Mitigation: designate an internal owner, keep a runbook covering signature debugging (openssl CLI verification of the envelope), and maintain captured request/response fixtures from the partner's sandbox.
• Knowledge concentration is the real support risk — typically one engineer understands the envelope. Force a second pair of eyes during the initial build and document the algorithm suite in the repo.

Scaling

• SOAP calls are synchronous and blocking; throughput is bounded by partner latency, not by our infrastructure. Put every non-interactive call behind a queue with per-partner rate limiting.
• Horizontal scaling is straightforward — the library holds no shared state — but each worker needs the keystore mounted. Avoid baking PEMs into images; mount or fetch at boot.
• Under Octane, keep clients request-scoped and watch for memory growth from repeated WSDL parsing; enable and warm soap.wsdl_cache (or ship local WSDL copies) to avoid a WSDL fetch on every request.
• Set aggressive connection_timeout and timeout values. A hung SOAP call inside a web request is a worker-exhaustion incident.

Failure modes

• Certificate expiry or wrong key → signature rejected, generic fault, often only discovered in production if staging uses a different cert.
• Clock skew → Timestamp outside the partner's window; intermittent and confusing. Enforce NTP and monitor drift.
• Canonicalization/namespace mismatch → "invalid signature" for payloads that look identical. Extremely hard to diagnose without envelope-level diffing.
• WSDL unavailable → client construction throws before any request; cache or vendor the WSDL.
• SOAP fault masking → partners return HTTP 500 with a fault body; naive error handling reports "server error" and loses the real message. Parse SoapFault->detail.
• Non-idempotent retries → queued retries can double-submit a payment. Require partner-side idempotency keys or restrict retries to read operations.
• Secret leakage → private keys and signed envelopes in logs. Redact by default; gate full-envelope logging behind a debug flag.

Ramp-up

• A mid-level Laravel developer with no SOAP background: ~1 week to ship a first integration with review, ~2–3 weeks to be genuinely independent on signature debugging.
• Prerequisites worth confirming before staffing: comfort with XML namespaces and canonicalization, basic X.509/openssl literacy, and understanding of WS-Security profiles. These are the actual bottleneck, not Laravel familiarity.
• Lowest-friction onboarding is a working fixture pair (signed request + partner response) committed to the repo as a golden test — it turns an arcane debugging exercise into a diff.
• Given the score profile (130 stars, modest opportunity signal), treat this as a narrow, deliberate adoption: excellent for the specific problem of WS-Security on ext/soap, and a poor general-purpose HTTP integration choice. Justify it only when a counterparty mandates WS-*.