Ras Laravel Package

Getting Started

This package is a Laravel integration for LEDI (Modelo de Informação para Registro Eletrônico em Saúde), the Brazilian health-interoperability standard. Version 1.6.0 bumps the underlying conformance target to LEDI 8.4.0, so anything you produce or validate is now expected to match the 8.4.0 specification rather than the previous revision.

Minimal path to first output:

1. composer require the package, then check composer.json for the service provider / facade alias — the provider is usually auto-discovered, but confirm the namespace before writing imports.
2. Publish the config (php artisan vendor:publish --provider=...) and read it top to bottom. Schema-version constants almost always live there; verify it now reads 8.4.0.
3. Look for shipped Artisan commands (php artisan list | grep -i ledi). A validation or generation command is the fastest smoke test that the upgrade landed correctly.
4. First real use case: take one existing record from your database and run it through generation → schema validation → XML output. Diff that output against a document you generated on 1.5.x. That diff is your entire upgrade checklist.

Start with the package's own test fixtures for 8.4.0 — they encode the field-level expectations faster than the spec PDF does.

Implementation Patterns

Model-to-document mapping. Keep a thin mapping layer between your Eloquent models and the LEDI structure rather than letting the package read models directly. When the standard revises (as it just did), you change one mapper instead of hunting field names across the app.

Validate at the boundary, not only on export. Run the package's validator when data is saved and again before export. The 8.4.0 schema is the authority; catching an invalid CNS/CPF or a newly-required field at save time beats discovering it in a batch export at 2am.

Version-stamp every artifact. Persist the LEDI version alongside each generated document (ledi_version column or a sidecar file). Once 8.4.0 output starts mixing with historical 8.3.x files, you need to know which is which for audit and for re-submission to SIS/ANS.

Queue the heavy work. Generation and validation of large record sets belong in a job. Pattern: GenerateLediDocument job → writes to a Storage disk → fires an event → notification with a signed download URL.

Config-driven version pinning. If the config exposes the target schema version, bind it to an env var so staging can stay on the old revision while production cuts over, instead of forking the package.

Fixture-based regression suite. Commit a small corpus of known-good 8.4.0 XML. Assert your generated output is schema-valid and that the fields you care about survive. This is the single highest-leverage thing you can add during a schema bump.

Gotchas and Tips

• The release notes are one line. "Atualiza para o LEDI 8.4.0" gives you no migration guide, no changelog of added/removed/renamed fields, and no statement about backward compatibility. Treat this as a potentially breaking release until you have diffed generated output. Read the LEDI 8.4.0 specification changes directly.
• Consumers may lag. The receiving system (municipal/state SIS, ANS) might still accept 8.3.x only. Confirm the counterpart's accepted version before deploying — a technically correct upgrade can cause rejected submissions.
• Silent output drift. If generation succeeds and validation passes but fields changed shape, nothing errors — you just submit wrong data. Snapshot tests on the XML are the only reliable guard.
• Config cache. After upgrading, run php artisan config:clear (and re-cache). A stale cached config can keep the old schema constant alive and produce a confusing half-upgraded state.
• Encoding and locale. LEDI documents are accent-sensitive and date/ decimal formats are strict. Check charset in the generated XML header and that config('app.locale') changes haven't altered number formatting in your mappers.
• Large documents. DOM-based generation will hit memory limits on bulk exports. Prefer streaming or chunked generation, and set an explicit memory ceiling in the job rather than inheriting the CLI default.
• Debugging strategy. When validation fails, dump the raw XML and validate it against the official 8.4.0 XSD with an external tool (xmllint) before blaming the package. That separates "my mapping is wrong" from "the library emits invalid XML" in one step.
• Extension points. Look for a validator contract or macro/extension hook before forking — custom business rules belong in your own validator class registered via the container, not patched into vendor code, or the next schema bump will be painful.
• Pin the version. "vendor/package": "~1.6.0" — a caret range on a package that tracks an external standard can silently move you to a schema revision your downstream consumer does not accept.