Download the PHP package chemaclass/edifact-parser without Composer

📦 EDIFACT Parser

A complete PHP toolkit for UN/EDIFACT — read, write, validate, and stream EDI interchanges with a typed, object-oriented API.

EDIFACT — Electronic Data Interchange For Administration, Commerce, and Transport — is the international standard for structured business documents (orders, invoices, despatch advices, transport instructions). 🔍 New to it? Start here.

Why this library

• 📥 Parse any interchange — unknown tags degrade gracefully to raw values, so no message type is unsupported.
• 📤 Write it back — serialize segments to a valid .edi string, or assemble a full UNB…UNZ interchange with auto-computed control counts.
• ✅ Validate — pluggable rule sets for required segments, cardinality, and order.
• 🌊 Stream — parse multi-gigabyte files in bounded memory (one message at a time).
• 🧱 Model the full envelope — interchange → functional groups (UNG/UNE) → messages, with duplicate-preserving access and typed metadata on every envelope segment.
• 🏷️ 32 typed segments out of the box with domain accessors, plus qualifier constants — or 134 with the directory bundle, and trivially extensible with your own.
• 📐 Directory-aware — validate elements, lengths, representations and code lists against the real UN/EDIFACT directories, and group messages into their actual nested segment groups (SG1…SGn) rather than a heuristic.
• 🖥️ CLI included — edifact parse|inspect|validate|segments, JSON on stdout, documented exit codes.
• 🩺 Structured diagnostics — stable codes and positions across parsing and validation, so failures are matched on, not string-searched.
• 🔎 Fluent query API and a statistics analyzer for extracting data. Results, messages, line items and queries are all Countable and iterable, and any of them dumps to plain arrays or JSON.
• 🌍 Charset-aware (UNOA…UNOY), strictly typed (PHP 8.0+, PSR-4), and fully covered by PHPUnit, PHPStan, Psalm, Rector and PHP-CS-Fixer.

Table of Contents

• Upgrading from 6.x
• Command line
• Quick Start
• Streaming large files
• Built-in segments
• Writing EDIFACT
• Validation
• Extending
• Debugging
• Development
• Contributing

For AI coding agents: docs/llms/. Every snippet there is backed by a runnable file under example/ that CI executes.

💾 Installation

Requires PHP 8.0+ with ext-json and ext-mbstring.

🚀 Quick Start

The parser never throws on unknown segments — they become UnknownSegments you can still read via rawValues(), so you can process any interchange and add typed segments later.

📥 Parsing

EdifactParser::parse() / parseFile() return a ParserResult:

A message starts at UNH and ends at UNT; an interchange wraps messages between UNB and UNZ, optionally grouped by UNG/UNE. Invalid input throws InvalidFile.

Choosing a tokenizer

Turning raw text into segments is pluggable. NativeTokenizer is the default — a regex-free single-pass scanner, ~1.8× faster at tokenizing (~1.3× on parse() overall), and it never rewrites the bytes it reads:

SabasTokenizer delegates to sabas/edifact, which was the default up to 6.x. It is still available, but be aware it strips every byte in \x80-\xFF — NAD+BY+++Müller comes back as Mller:

Reach for it when you need bug-for-bug compatibility with 6.x, or want the restricted UNOB repertoire enforced. Otherwise the default is both faster and lossless.

For ASCII input the two tokenize identically — verified segment-for-segment across the test fixtures and a generated corpus.

Streaming large files

Stream messages one at a time in bounded memory — ideal for large interchanges. A leading UNA service-string advice (custom separators/release char) is honoured automatically:

🖥️ Command line

composer require installs an edifact binary. It answers "what is in this file?" without writing a script — and it is built for automation as much as for people:

Contract, so output can be consumed without guessing:

• data on stdout, diagnostics on stderr — never interleaved, so | jq always works
• exit codes: 0 success/valid, 1 invalid input, 2 usage error
• JSON by default; --pretty is purely cosmetic

No console framework is pulled in — a parsing library should not put one in your vendor/.

📖 Reading data

Typed accessors

Typed segments expose their fields as methods — self-documenting and IDE-friendly:

Every segment also exposes the raw structure when you need it:

Accessing segments

Dumping a message

toArray() / toJson() render a whole message — or a single segment — as plain data, with context children nested. Useful for logs, snapshot tests and diffing interchanges:

Fluent query API

Chain filters and transformations over every segment (order preserved, duplicates included):

query() and $message->segments() return every segment in original order, duplicates included. The keyed lookups (segmentByTagAndSubId(), allSegments()) index by tag + subId and keep the last occurrence — use the query API when duplicates matter.

Line items

Line items group each LIN with its related detail segments (QTY, PRI, PIA, …) — ideal for orders and invoices:

Hierarchical context segments

Context segments preserve parent → child relationships (e.g. NAD → CTA → COM):

Keyed lookups always hand back the typed segment, so you can go the other way too — read a segment normally, then ask the message what was grouped under it:

Interchange & envelope metadata

Every envelope segment exposes typed metadata:

Functional groups (UNG/UNE)

When an interchange wraps messages in UNG…UNE groups, read them directly. Interchanges without groups return an empty list — messages stay available flat via transactionMessages():

Statistics & analysis

MessageAnalyzer extracts counts and aggregates:

Qualifier constants

Avoid magic strings with typed qualifier catalogs (IDE autocomplete, usable in match):

Character sets

The parser reads raw bytes. Decode non-ASCII values to UTF-8 from the interchange's syntax identifier:

UNOA/UNOB → ASCII, UNOC–UNOK → ISO-8859-*, UNOY → UTF-8.

Built-in segments

32 segments are typed and registered by default (134 with SegmentFactory::withDirectorySegments()):

• Envelope / service: UNB, UNG, UNH, UNS, UNT, UNE, UNZ
• Header: BGM, DTM, RFF, NAD, CUX, TDT, LOC, FTX
• Party / terms: CTA, COM, PAT, PCD, TAX, TOD
• Detail / summary: LIN, PIA, IMD, QTY, PRI, MEA, PAC, GID, MOA, PCI, CNT

Any other tag parses as an UnknownSegment (readable via rawValues()); add your own typed class in a few lines — see Extending.

📤 Writing EDIFACT

Build individual segments

Fluent, type-safe builders produce segment objects:

NADNameAddress, QTYQuantity and PRIPrice provide ::builder().

Serialize segments to a string

EdifactSerializer is the inverse of parsing — it round-trips a parsed interchange byte-for-byte and escapes separators/release chars for you:

Assemble a full interchange

InterchangeBuilder writes a complete UNB…UNZ interchange and fills in the UNT segment counts and the UNZ control count automatically:

✅ Validation

Check a message against a pluggable rule set — required segments, cardinality, and relative order. The validator never throws; an empty result means the message conforms:

Ready-made rule sets for common message types are provided as starting points:

🔧 Extending

Custom segments

Extend AbstractSegment and register your class. The shared accessor helpers (element(), component(), firstComponent()) safely read simple and composite elements:

withAdditionalSegments() keeps every default and merges your tags on top — registering a custom class under a default tag overrides that default. Use withSegments() instead when you want an explicit, closed set of segments.

Introspection

Ask the factory what it knows, instead of reading the source:

Descriptors are derived by reflection, so they cannot drift from the code. registeredTags() and classForTag() read the map only — no class is loaded.

The shape of toArray()/toJson() is published as a JSON Schema at schema/message.schema.json, and a test asserts the schema still matches what a parsed message actually produces.

Composable segment bundles

The defaults are exposed as two composable bundles so you can build a lean factory that only types the tags you care about — everything else still parses as a readable UnknownSegment:

• SegmentFactory::ENVELOPE_SEGMENTS — the UN* service/control segments (7).
• SegmentFactory::BUSINESS_SEGMENTS — header, party/terms, detail and summary (25).
• SegmentFactory::DEFAULT_SEGMENTS — the union of both (32).

Custom grouping rules

Context hierarchies and line-item boundaries are driven by GroupingRules. Pass a customized instance to change which tags open a context, attach as children, or close a line-item section:

GroupingRules also reads back what it is configured with — contextTags(), childTags(), breakLineItemTags() — and the defaults are exposed as GroupingRules::DEFAULT_CONTEXT_TAGS, DEFAULT_CHILD_TAGS and DEFAULT_BREAK_LINE_ITEM_TAGS.

More examples in extracting data, query filtering, printing segments, context segments.

🐛 Debugging

Error handling

Structured diagnostics

Matching on English prose is fragile, so parse failures and validation failures share one type with stable codes and, where known, a position:

Codes are public API — see DiagnosticCode for the catalogue. Messages are not: they may be reworded at any time.

🛠️ Development

CI runs the benchmarks on every pull request, measuring the base branch and the head branch on the same runner and failing when a metric regresses beyond 1.5×. Absolute timings on shared hardware mean little; ratios measured back to back do. Never change tools/benchmark.php in a commit that also reports a performance delta — the numbers stop being comparable.

• PHP 8.0+, strict types, PSR-4. Type hints and tests required for new functionality.
• All code must pass PHP-CS-Fixer, Psalm, PHPStan and Rector (CI is authoritative).

Local toolchain note: the pinned Psalm (vimeo/psalm ^4.30) runs on PHP ≤ 8.3 — run it under 8.3 if your CLI is newer. On PHP > 8.3, PHP-CS-Fixer needs PHP_CS_FIXER_IGNORE_ENV=1.

🤝 Contributing

Contributions of all kinds are welcome — bug fixes, ideas, and improvements.

• 🐛 Report an issue
• 🔧 Open a pull request

📋 See the contributing guide to get started.