Daplos Bundle Laravel Package

Getting Started

This release (v0.10.0) is a behavior change, not a new API surface — nothing to install, but plan a validation pass before deploying.

1. Read the two docs that changed first: docs/utilisation-code.md (new section listing every controlled/uncontrolled field per FLAG) and docs/exporter.md (new "Troncatures" section). These are now the source of truth for what the validator will complain about.
2. Check your config: if you publish the package config, the new key is exporter.fail_on_truncation (default false). Laravel apps that version a generated reference file will also see the option appear there — commit it.
3. Smoke-test with your real reference files before shipping: run your existing parse → validate pipeline against a handful of production DAPLOS files (DP and VI are the highest-risk FLAGs) and diff the error lists against v0.9.1.

First use case to wire up after upgrading: take a file you know is accepted today, push it through StrictReferentialValidator, and confirm you can tolerate the new signals — most commonly codeUniteRendement at DP 103-105 reporting ZHK, a unit used by real-world issuers but missing from the synced "Unité de mesure" referential.

$document = $parser->parse($contents);

foreach ($validator->validate($document) as $error) {
    // v0.10.0: more errors here than before, same shape
    Log::channel('daplos')->info($error->getMessage(), ['flag' => $error->getFlag()]);
}

Implementation Patterns

Treat the validator as a reporting layer, not a gate. The release is explicit: it signals, it never blocks. Keep the accept/reject policy in your application so a validator bump can't silently start rejecting imports.

$errors = $validator->validate($document);

$blocking = collect($errors)->reject(
    fn ($e) => in_array($e->getCode(), config('daplos.known_unit_warnings'), true)
);

if ($blocking->isNotEmpty()) {
    throw new ImportRejected($blocking);
}

Because v0.10.0 adds ~20 field checks in one go, an explicit allow-list of "known noise" codes (like ZHK) is cheaper than pinning the package version forever, and it documents why each is tolerated.

Persist validator output rather than just logging it. Store errors alongside the import record (FLAG, position, code, raw value, line number) so a package upgrade that adds checks shows up as a diff in a report rather than a surprise in a support ticket. This makes the v0.11.0 upgrade a data comparison instead of a re-test.

Decide truncation policy per environment. Default is unchanged output with no exception thrown — silent truncation, now observable:

$exporter->exportToFile($document, $path);

foreach ($exporter->getTruncations() as $t) {
    // ExportTruncation: FLAG, position, length, line, full value, written value
    Log::warning('DAPLOS truncation', [...]);
}

• local / staging: exporter.fail_on_truncation => true, catch DaplosExportException and treat it as a test failure. Note exportToFile() does not write the file when it throws — don't assume a partial file exists.
• production: keep false and alert on a non-empty getTruncations() so a bad import doesn't become a failed customer export.

Keep a round-trip regression test. The parse(export($document)) identity holds only while nothing is truncated. Any fixture that exercises wide DT/PV fields can now break that invariant, so assert both the round-trip and getTruncations() === [] for it.

Custom writers need one decision. If you extend AbstractLineWriter, truncation reporting is free — change nothing. If you implement LineWriterInterface directly, you keep working but your writer's truncations are invisible to getTruncations(); migrate to the abstract class if you rely on the new signal.

Re-sync the referential as a deploy step. daplos:sync --all must be re-run to decode labels already persisted with HTML entities (’, “, –, …). Codes were never affected, so re-syncing is safe. In Laravel, schedule it as a post-deploy job — and remember the command shown in the notes is the console form; from application code call the sync service or Artisan::call() whatever thin wrapper you use.

For UI-facing imports, group new errors by parcelle/line before display. Several of the new checks (HA 15-17, VR 88-90, IL 126-140) are unit codes that repeat across many rows, so a raw error list becomes unreadable fast.

Gotchas and Tips

• Previously valid files can now be invalid. This is the headline risk. Any code that treats a non-empty validator result as "reject the file" will start rejecting files it accepted yesterday. Audit those call sites first.
• Four checks were removed. If you had error-handling keyed on ParcelleCulturale::codeJustificationCulture, codeUniteSurface, codeModeProduction, or Historique::codeTraitementResidus, those errors will simply stop appearing. The fields aren't in guide v0.95 and the parser never filled them — remove any dead suppression logic. Residual management of the previous crop is now checked via codeGestionResidus.
• ZHK will fire on every parcelle that carries it, at DP 103-105. Expect a volume change, not a one-off.
• Truncation is on by default in the "silent" sense. Upgrading changes nothing about the file you write — which is exactly why you must read getTruncations() if you care. Ignoring the new API means no behavioral change at all.
• Re-exporting a file that round-trips today can now truncate. The parser deliberately reads DT from position 26 and PV BBCH from position 485 to end of line (never lose data), but the guide widths are DT 26-45 and PV 485-494. A file with wide values parses fine and exports truncated — now reported. Same story for PV intervention comments past the two 70-character zones. If your fixtures were built to stress the parser, watch them.
• SC/CC/VC coordinate fields are an (alphanumeric) in the guide but float in the DTOs. The numeric value survives; the written form does not (leading zeros, formatting). Unchanged in this version but now documented as a known limit — don't build checksums or byte-exact comparisons on those fields.
• HTML entity decoding is labels-only. If you index or key anything off a label, expect it to change after daplos:sync --all; codes remain stable, so key off codes.
• Extension points to lean on: Exporter\Contract\TruncationAwareInterface for your own exporter decorators, AbstractLineWriter for writers, and the validator's error objects (unchanged signatures — no rewrite needed).
• Debugging tip: when a new error looks wrong, check docs/utilisation-code.md for whether the field is in the controlled list at all. The v0.10.0 table is deliberately exhaustive, and "field is no longer checked" is a real explanation for a disappearing error.