Totvs Rm Soap Laravel Package

Technical Evaluation

Architecture fit. TOTVS RM is an ERP whose integration surface is SOAP — there is rarely a REST alternative, so the realistic product decision is not "SOAP or no SOAP" but "hand-rolled envelopes or a wrapper." This package is the wrapper: a WebService abstraction with fail-fast behavior and caching, XML generators, and a Laravel service Provider exposing transient/shared bindings. For a Laravel product that must call RM (cadastro de clientes, pedidos, financeiro, RH), that means the highest-maintenance slice of integration code — XML envelopes, auth, transport bootstrapping — is a dependency instead of bespoke code. The transient vs shared distinction is the one architectural fact a TPM should force onto the design review: it determines whether state is scoped per call or held across calls, which directly affects worker safety under Octane/queues.

Integration feasibility. Favorable on the evidence available. illuminate/* and phpdotenv appear only in require-dev (test scaffolding), implying production dependencies are essentially Laravel plus PHP's SOAP extension — a small install surface, low CVE exposure, and no framework version hostage-taking. The package ships its own PHPUnit bootstrap, so it will not collide with an existing test suite; that materially lowers the cost of introducing it into a mature codebase. The one hard prerequisite to confirm in M0 is ext-soap being installed, declared, and present in every environment including CI and production images.

Technical risk. The dominant risk is not code quality, it is adoption and longevity. Signals: 1 star, 0 dependents, single maintainer, MIT. That is a bus-factor-of-one dependency on an interface the business cannot afford to lose. Mitigating factors: MIT license and a small, well-understood abstraction mean forking is cheap if the maintainer disappears; v4.5.0 is a hardening release (docs, 57 tests / 158 assertions, Pint + PHPStan, Dependabot) rather than a feature release, so the code is being stabilized rather than churned. The second risk is the untested boundary: tests are mocked-SoapClient happy paths plus fail-fast/cache/provider behavior — there is no evidence of live-endpoint testing or negative-path coverage against a real WSDL. The release date metadata also does not resolve cleanly against the changelog, so release cadence should be treated as unknown.

Key questions.

• Which RM services/WSDLs are in scope, who on the ERP side owns their versioning, and what is the change-notification process?
• Is ext-soap declared as a platform requirement, and what are the minimum PHP and Laravel versions?
• What are the cache TTL and invalidation semantics, and are they configurable per service?
• Are transient and shared bindings documented for consumers, or only tested internally?
• Who is the accountable maintainer internally, and what is our fork/patch posture if upstream goes quiet?
• Do we have homologation/sandbox credentials for RM, and when?
• Is there commercial support behind this, or is community-only acceptable for a revenue-adjacent integration?

Integration Approach

Stack fit. Conventional Laravel app with the framework container, config, and the PHP SOAP extension. No exotic runtime requirements are evidenced. This fits a standard service-layer design: the package owns transport and envelope concerns, our domain code owns mapping and business rules. Keep that boundary explicit in code review, because the temptation is to leak RM schema details upward.

Migration path. Treat as greenfield adoption, not an upgrade. Pin ^4.5.0, install into a single bounded context first (one RM service), and prove it against the homologation endpoint before any production credential is issued. Do not publish the config or wire bindings globally on day one — scope them to the pilot module so rollback is a config change, not a revert.

Compatibility. 4.5.0 is additive only: docs and tests, no removals or deprecations. Package-API compatibility risk is low. The real compatibility surface is external — RM WSDL versions — and that is outside the package's semver guarantees. Budget for it as an ongoing contract-management activity, not a one-time integration task.

Sequencing.

1. M0 — Environment readiness. ext-soap in all environments, PHP/Laravel floor confirmed, network egress to RM endpoints, sandbox credentials, secrets handling.
2. M1 — Spike. One read-only RM call end to end against homologation using the documented happy path. Exit criterion: a typed, inspectable failure when the endpoint is wrong — proving fail-fast works, not just the success path.
3. M2 — Wiring. Publish config, bind the provider, and make an explicit transient-vs-shared decision with the tech lead, documented in the ADR.
4. M3 — Pilot in production shape. One endpoint behind a feature flag; instrument latency and error rates before enabling caching.
5. M4 — Resilience. Cache TTL/invalidation agreed; retry and circuit-breaker expectations assigned to the caller; runbook written.
6. M5 — Rollout. Remaining services onboarded one at a time, each with its own contract review.

Scope guardrail. Use this for synchronous, request-scoped integrations. If a requirement is bulk data movement, long-running jobs, or high throughput, that is a queue/batch design problem — do not let it get absorbed into this package's scope.

Operational Impact

Maintenance. Quality gates are credible and citable in a go/no-go: Pint, PHPStan, 57 tests / 158 assertions, Dependabot. That answers "is this maintained?" better than star count does. It does not answer "who maintains it if the author stops?" — so name an internal owner, and record the fork decision as a pre-approved fallback rather than a hypothetical. Separately, budget a recurring RM contract review (WSDL diff, field deprecations) on a fixed cadence; that work is independent of package upgrades and will be the actual source of breakage.

Support. docs/SERVICES.md and docs/TROUBLESHOOTING.md materially raise first-line supportability; troubleshooting content is what on-call needs. But support ownership is split across a boundary — RM transport/credentials versus package behavior versus RM-side configuration — and that boundary must have a named escalation path into the ERP team. Gaps to close internally: cache behavior under upstream failure, and upstream-version-mismatch symptoms.

Scaling. Caching is the primary lever and the primary unknown: without documented TTL/invalidation, concurrency behavior must be validated under load before it is trusted. SOAP is synchronous, so throughput is bounded by RM response latency — set explicit timeouts, plan connection reuse, and model the ERP as the bottleneck in capacity planning. Under Octane or queue workers, do not hold shared bindings across requests unless state-safety is confirmed; default to transient and justify any exception.

Failure modes. Enumerate and assign an owner and a handling decision for each before production: RM unavailable, WSDL/schema drift, malformed generated XML, stale or poisoned cache, expired or rotated credentials, and fail-fast exceptions surfacing to end users. Fail-fast is the right default — it prevents corrupt downstream writes — but it explicitly shifts retry, circuit-breaking, and graceful-degradation work onto the calling code. That work is in scope for the plan; it is not free.

Ramp-up. Roughly a day for a mid-level Laravel engineer to be productive: the provider/binding pattern will be familiar, and the new docs plus a 30-minute sandbox walkthrough cover the mechanics. The genuine skill gap is SOAP/XML debugging and RM domain knowledge, which is weeks, not days. Plan for at least two engineers to touch the integration so the ERP contract knowledge is not single-threaded — the same bus-factor concern that applies upstream applies to us.

Success measures for the pilot. Integration code volume versus a hand-rolled baseline, p95 latency against RM, error rate by failure class, cache hit ratio, and mean time to diagnose an RM-side failure.