Daplos Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for DAPLOS interop. The v0.10.0 validator now checks every coded field across 11+ FLAGs (DP, PS, PH, HA, PV, VH, VI, IC, IL, VR, LC) against the v0.95 guide nomenclature — hundreds of fixed-width positional fields. Maintaining that mapping in-house is a standing tax that resets with each guide version. This is a strong argument for adopting rather than building.
• Roadmap: the guide v0.95 migration. The release formalizes v0.95 as the target: fields absent from v0.95 are no longer validated, and coverage is expanded. That makes "we are v0.95-ready" a demonstrable milestone rather than a claim.
• Feature: a pre-import validation gate with real diagnostics. Because the validator emits per-field results (FLAG, position range, field name, expected nomenclature) and never blocks, you can build a review screen — "42 issues, grouped by FLAG, exportable to CSV, acknowledged with justification" — instead of surfacing an opaque parse failure. That is a differentiated UX in agri-data ingestion, where competitors typically reject the file or swallow the error.
• Feature: export integrity / no silent data loss. getTruncations() returns structured ExportTruncation records (FLAG, position, length, line number, original value, written value) after every export. This directly supports a "3 values were shortened to fit the standard — review" banner in the UI, and exporter.fail_on_truncation: true supports regulated or archival exports where a cut value is unacceptable. Default behavior is unchanged, so it ships behind a policy switch.
• Data-quality instrumentation. Validator errors are now a measurable signal per emitter/source. Prioritize outreach — the release already names a concrete case: unit code ZHK appears on real market files but is absent from the synchronized referential, so every parcel carrying it is flagged. That is either a false-positive to suppress or an upstream data-quality conversation; the package lets you see it and decide.
• Referential freshness as an operational concern. Label decoding from the API (HTML entities such as ’) is fixed, with a re-sync path. If your product displays referential labels, this is a visible-quality bug fix, not a housekeeping item.
• Buying signal, not a blocker: the release is additive (no signature changes, no code changes required) but does tighten semantics. It is safe to adopt; the decision it forces is policy (warn vs. reject), not engineering capacity.

When to Consider This Package

Adopt when:

• You ingest or produce DAPLOS fixed-width files in a PHP/Laravel application and want the parsing, DTOs, validation, and export in one dependency.
• You want validator output as structured objects you can render, filter, and log — not text you have to scrape from a CLI checker.
• You are on, or moving to, guide v0.95, or you need to find out whether your existing corpus actually conforms (this release is a cheap audit: run your reference files and read the new errors).
• You need an auditable export path: truncation records plus an opt-in hard-fail give you a defensible "we did not silently corrupt the file" story.
• You value a staged adoption: validation signals without blocking, truncation reporting without changing output bytes.

Look elsewhere or add guardrails when:

• You need compliance certification. This validator signals; it never blocks. It is a quality tool, not an authority — your application owns the accept/reject policy, and a clean run is not a legal guarantee.
• Your integration is XML, EDI, or API-first. This is a fixed-width guide implementation.
• You rely on custom LineWriterInterface implementations. Only AbstractLineWriter subclasses report truncations without code changes; a writer implementing the interface directly keeps working but goes dark on truncation detection. Budget a small refactor if export integrity matters.
• You need round-trip losslessness. Two documented gaps: (1) SC/CC/VC FLAG fields are alphanumeric in the guide but carried as float in the DTOs — numeric value survives, written form does not; (2) the parser reads DT (26-45) and PV (485-494) past the guide width to avoid losing data, so re-exporting such a file truncates. It is now reported, not prevented.
• You cannot refresh the referential. Validation quality is bounded by the last daplos:sync; the ZHK case shows gaps produce false positives on legitimate market files. If sync runs against a source you do not control, plan for a suppression list.
• Verify L1 wiring first. The notes reference php bin/console daplos:sync and a generated config/reference.php, i.e. Symfony-shaped conventions, while the package is being evaluated for Laravel/PHP use. Confirm before committing: service-provider binding for DaplosFileExporter, console-command registration, config publishing, and where exporter.fail_on_truncation lives in a Laravel config tree.
• Maturity caution. At v0.10.0 (pre-1.0), behavior can still tighten in a minor — this release did exactly that, adding errors on files that previously passed and removing validator controls for fields not in v0.95. Pin the version and re-run your reference corpus on every bump.

Migration cost (low, but not zero): re-run daplos:sync --all; decide whether to opt into fail_on_truncation; if you render or act on validator errors, expect new ones — especially codeUniteRendement values of ZHK. No signatures change.

How to Pitch It (Stakeholders)

For executives (one paragraph). This release converts a silent-failure risk into a managed one. On the inbound side, every coded field in a DAPLOS v0.95 file is now checked against the official nomenclature, and problems are reported per field rather than surfacing as a failed import — which means we can show users exactly what is wrong with their file and keep the transaction instead of losing it. On the outbound side, values that get shortened to fit the standard are now recorded and can optionally block the export, so we can state credibly that we never hand a regulator or a customer a quietly corrupted file. Both capabilities are additive: no API changes, no rework, and the export bytes are identical to the previous version unless we deliberately opt in. The strategic case is build-vs-buy: the DAPLOS guide is a large fixed-width specification that re-issues periodically, and maintaining that mapping in-house is permanent overhead with no product upside.

For engineering (what to actually do). Three migration steps, no code changes required. (1) Re-run the referential sync (daplos:sync --all) to decode HTML entities that have been persisted in labels — codes are unaffected. (2) Wire getTruncations() — available on DaplosFileExporter and any TruncationAwareInterface implementation — into logging or a user-facing warning after each export; the default non-blocking behavior is preserved. Optionally enable exporter.fail_on_truncation: true for archival or regulated exports, which throws DaplosExportException and does not write the file. (3) If we surface or gate on validator errors, expect new ones on previously valid files, most consistently codeUniteRendement = ZHK from certain market emitters — decide our warn-vs-reject policy and seed a suppression list before enabling the gate. Two things to confirm rather than assume: our Laravel wiring (the release notes are Symfony-shaped: bin/console, generated config/reference.php), and whether any custom writer implements LineWriterInterface directly — those still work but will not report truncations, and should be moved onto AbstractLineWriter.

The one caveat worth stating out loud. Tightening validation in a minor version is a behavior change even though no signature moved. Files that passed yesterday may be flagged today. That is the feature, not a regression — but it belongs in the release note we send to customers, not in the changelog they discover.