Edifact Mapping Laravel Package

Getting Started

• Install with composer require php-edifact/edifact-mapping. In practice you'll usually get it transitively when you install php-edifact/edifact, which consumes it.
• Look first at two places: vendor/php-edifact/edifact-mapping/src/ for the loader classes (typically MappingProvider and its message/segment/element models), and the shipped XML directory for the actual definitions. Open one file end-to-end — say ORDERS under D96A — because that XML is the schema you're really programming against.
• Understand what it is: a data/schema package, not a service. There's nothing to configure, no migrations, no service provider you need to wire up. It loads XML descriptors that describe a message's segments, composite elements, and data elements for a given message type and EDIFACT directory.
• First use case: pair it with EDI\Writer to emit an ORDERS/DESADV/INVOIC and let the mapping enforce segment order and mandatory elements. If you're not writing yet, use it standalone to answer "which segments does ORDERS D96A allow, and which are mandatory?" — that introspection is the fastest way to see the value.

use EDI\Mapping\MappingProvider;
use EDI\Writer;

// message type + directory/version; confirm the exact constructor
// signature in src/Mapping/MappingProvider.php for your installed version
$mapping = new MappingProvider('ORDERS', 'D96A');
$writer   = new Writer($mapping);

Implementation Patterns

• Write path. Build one provider per message-type/directory combination and hand it to the writer. Derive the payload from your domain object and let the mapping drive segment order, rather than hand-assembling segments and hoping.
• Read path. Parse inbound files with EDI\Parser/Reader, then use the mapping to assert required segments and elements exist before mapping into your DTOs. This is where mappings earn their keep: partner files that "look fine" but violate the schema get rejected with a structural reason instead of blowing up three layers deeper.
• Wrap it, don't sprinkle it. Create a small repository — EdifactSchemaRepository::segmentsFor($type, $directory), elementSpec($tag, $component) — that owns the provider. You get a single seam for caching, testing, and swapping in a custom XML directory, and MappingProvider never leaks into controllers.
• Schema-driven tooling. Because the definitions are plain XML, they're ideal for segment explorers, field pickers, admin UIs, or generating DTOs/stubs. Treat it as a metadata source, not just a validator.
• Round-trip tests. Keep known-good partner files as fixtures and run parse → map → write → assert against the mapping. Directory drift and version mismatches show up here cheaply.
• Long-running workers. Register the provider as a singleton under Octane or queue workers; XML parsing per job is pure waste, and the mappings are immutable at runtime.
• Contribution path. When a partner sends a message/directory you don't have, the clean fix is adding the XML upstream (or in your own directory and loading it via a subclass) rather than patching vendor/.

Gotchas and Tips

• Directory version is the whole ballgame. ORDERS D96A and ORDERS D01B are different schemas. A message whose UNH says ORDERS:D:01B:UN will not validate against a D96A mapping. Match the mapping to the partner's actual interchange version, not to what your ERP prefers.
• Coverage is not universal. The package ships a subset of message types and directories. Confirm the XML exists before designing around a message. If it's missing, you can often add the XML locally, or fall back to writing segments manually — the writer doesn't strictly require a mapping.
• Structural validation only. It tells you a segment is allowed and an element is mandatory; it says nothing about code values (qualifiers, currency codes, UN/ECE units). Validate those separately.
• Groups and repetition don't flatten cleanly. Nested segment groups (RFF-DTM inside SG1, for example) aren't always well represented by "walk each segment in order." Read how the provider exposes group structure before building a validator on top of a flat segment list.
• Failures are terse. A missing XML file or an unknown tag tends to surface as a generic exception or a null segment. Wrap provider calls and include the full identifier (type, version, release, agency) in your error message — otherwise you'll debug blind.
• Agency and release fields matter. EDIFACT identifiers include the controlling agency (UN, ODETTE, etc.). If lookups come back empty, dump the constructor arguments; the mismatch is almost always there.
• Packaging traps. XML paths are resolved relative to the package. PHAR bundling, relocated vendor directories, or Docker builds that strip non-PHP files break it silently. Keep the XML shipped and add a smoke test that loads one mapping.
• LGPL-3.0. Calling it from closed-source code is generally fine; modifying the package itself carries obligations. Prefer composition or subclassing, and never edit files in vendor — composer install will overwrite them anyway.
• Maintenance reality. Low stars, last release February 2023. EDIFACT directories are frozen, so low churn is expected — but budget time to read the source, pin the version, and own your own tests. Don't count on fast upstream fixes.