Edifact Laravel Package

Technical Evaluation

Architecture fit. sabas/edifact is a stateless, framework-agnostic transformation library: it converts UN/EDIFACT interchange text into segment/element trees (and back, via its builder), and nothing else. That narrow scope is a strength for our architecture — it belongs in the integration/anti-corruption layer, wrapped behind our own EdifactParser/EdifactBuilder interfaces so domain code never sees Sabas\Edifact\* types. It does not cover transport (SFTP/AS2/VAN), partner-specific mapping profiles, functional acknowledgements (CONTRL/997), code-list validation, or persistence of interchange state — all of which remain our build. Treat it as a parser dependency, not an EDI platform.

Integration feasibility. Composer-only install, no service provider, no framework coupling, no exotic extensions expected beyond standard string handling. Realistic first-parse proof of concept is 1–2 days; a production-grade inbound pipeline is 2–4 weeks including mapping and error handling. The main feasibility gate is not the package but whether we can obtain representative partner files (all message types, all partners, all edge cases) to test against.

Technical risk.

Key questions.

1. Which message types, directories (e.g. D96A/D01B), and partners are in scope for phase 1?
2. Is outbound generation (builder) required, or is this inbound-only initially?
3. Who owns the partner specification documents, and are they current?
4. What is our volume and peak-burst profile per hour, and what is our SLA for a message appearing in the ERP?
5. Do we need functional acknowledgements (CONTRL) and control-number reconciliation? If yes, that is custom work.
6. Do we have the right to publish a fork if we patch the library?
7. What is the current parsing solution, and what is the cost of leaving it?

Integration Approach

Stack fit. Laravel-native by accident rather than design — which is ideal. Recommended shape:

• app/EDI/Contracts/ — our interfaces (InterchangeParser, MessageMapper, AcknowledgementGenerator).
• app/EDI/Parsing/ — thin adapter over Sabas\Edifact\Parser; converts library objects into our own DTOs immediately.
• app/EDI/Mapping/ — per-partner, per-message-type mappers to a canonical internal model.
• app/EDI/Validation/ — syntax checks plus our own semantic rules; failures route to a quarantine table.
• app/EDI/Transport/ — separate concern (Laravel filesystem SFTP driver, or an existing MFT).
• Jobs: IngestInterchangeJob → ParseMessageJob (per message) → MapMessageJob → domain event.
• Persistence: interchanges (raw payload, sender/receiver, control refs, status), edi_messages, edi_errors.

Raw payloads are stored before parsing, always. That single decision makes reprocessing free when mappings change.

Migration path. If we currently parse with regexes, ad-hoc explode('+') code, or the predecessor php-edifact library, this is a drop-in conceptual replacement, but the 1.x API is a break from older versions — budget a rewrite of call sites, not a swap. If we use a commercial EDI/B2B vendor, the realistic path is not rip-and-replace: run this package in shadow mode against the vendor's output on live traffic, compare canonical results, and only cut over a partner at a time. That de-risks the migration and gives us a per-partner rollback lever.

Compatibility. Verify PHP constraint against our Laravel version before committing (Laravel 10/11/12 imply PHP 8.1+). No global/static state is expected in the parser, so Octane and long-running queue workers should be safe, but confirm on the spike. Pin an exact version in composer.json and treat upgrades as deliberate changes with a regression run, not routine composer update churn.

Sequencing.

1. Spike (week 1): parse 20–50 real files across the top 3 message types; measure accuracy, memory, and failure modes. Decision gate.
2. Adapter + golden files (weeks 2–3): interfaces, DTOs, regression corpus from real files.
3. Inbound pipeline in shadow mode (weeks 3–5): transport → store → queue → parse → validate → map, writing to a side table only.
4. Cutover per partner and per message type, starting with the lowest-volume partner.
5. Outbound generation (later phase): builder API wrapped behind our own MessageBuilder, driven by templates per partner.
6. Decommission the old path only after a full billing/fulfilment cycle has cleared on the new one.

Operational Impact

Maintenance. Low code surface, but the maintenance burden shifts to us: partner mappings, code lists, and validation rules are the real long-lived asset and will churn monthly. The library itself will need attention roughly on PHP major-version cadence. Budget ~0.2–0.3 FTE ongoing for the integration layer, plus mapping work per new partner (typically 3–10 days each).

Support. Community-only via GitHub issues; no vendor, no SLA, no security advisory process to rely on. We must be able to self-support: a developer who can read the library source and patch a fork is a hard requirement, not a nice-to-have. LGPL permits this, provided we publish modifications to the library itself.

Scaling. Parsing is CPU-bound and stateless, so it scales horizontally behind queue workers — add workers, not architecture. The constraints are (a) memory per interchange, so cap file size and chunk by message; (b) queue throughput during partner batch windows, which are usually bursty end-of-day; (c) database write amplification if we store every segment. Size the queue pool for the burst, not the average.

Failure modes and handling. Expect: truncated files, missing or mismatched UNB/UNZ control counts, unknown segment qualifiers, wrong element counts, encoding corruption, and partner-specific quirks that violate the standard. Each must land in a quarantine queue with the raw payload retained, an alert to the integration on-call, and a partner-facing rejection path. Silent partial parses are the dangerous case — assert on message counts against UNZ/UNT and fail loudly. Add idempotency on interchange control reference so retries do not double-post to the ERP.

Ramp-up. A mid-level PHP developer becomes productive with the API in 2–3 days. The real ramp is EDI domain literacy — envelope structure, qualifiers, control numbers, acknowledgement semantics, and reading a partner spec — which is 3–6 weeks to competence and is not provided by this package. Plan for one person to own that knowledge, with a second as backup, or the integration becomes a single point of failure regardless of how good the parser is.

Verdict. Good fit for the parsing layer of a Laravel-based B2B integration, at low adoption cost; not a substitute for an EDI capability. Proceed conditional on the spike against real partner files, legal sign-off on LGPL, and acceptance that validation, mapping, acknowledgements, and transport are our scope.