Laravel Gedcom Laravel Package

Getting Started

Install with composer require liberu-genealogy/laravel-gedcom. Laravel auto-discovery registers the service provider; if you're on an older setup, add LiberuGenealogy\LaravelGedcom\GedcomServiceProvider and the Gedcom facade alias manually. Publish the config only if you need to override defaults: php artisan vendor:publish --tag=gedcom-config.

First use case is the one you'll need 90% of the time: read a .ged file into records you can iterate. Reach for the facade (LiberuGenealogy\LaravelGedcom\Facades\Gedcom) rather than instantiating the reader directly — it gives you the container-resolved reader, which matters for testing and for custom subclasses.

Orient yourself in this order:

1. config/gedcom.php — file paths, encoding, and any parser options.
2. The underlying liberu-genealogy/php-gedcom value objects (Gedcom, Individual, Family, Source, Note, Tag) — the Laravel package is a thin container wiring around them.
3. GedcomGenerator — this is the class you subclass or bind against when you need custom output.

A minimal first pass: Gedcom::parse(storage_path('app/gedcom/family.ged')), then walk ->getIndividualRecords() and ->getFamilyRecords() to confirm the structure before you write any persistence code.

Implementation Patterns

Import into Eloquent. Parse in a queued job, not a controller. Convert each Individual/Family into your own model rows and store the raw GEDCOM line (xref id + blob) alongside the parsed fields so you can reconcile later. Always key your records on the GEDCOM xref (@I123@), not on names — names collide, xrefs don't.

Round-trip generation. Build a Gedcom aggregate from your Eloquent models and pass it to GedcomGenerator. Keep a serialization layer (models → GEDCOM objects) separate from the generator so you can swap the output path without touching domain code. This is where DI matters: v8.6.0 resolves Source through the container inside GedcomGenerator, so you can bind a custom Source class in a service provider and have every generated source record use it — cite/author metadata, repository refs, etc. — without touching package internals.

Testing. Bind a fake or in-memory reader in setUp() and assert on parsed records rather than on shelling out to files. Because the generator resolves Source from the container, you can also swap in a deterministic Source subclass in tests to make generated output byte-stable for snapshot assertions.

Multi-tenant / per-import config. If you process uploads for multiple trees, pass an absolute path per job and keep uploads out of storage/ if you can — object storage means downloading to a temp file first. Wrap imports in a DB::transaction and chunk large trees.

Export scheduling. For "download my tree" features, generate on a queue, store the .ged on the public disk with a signed URL and a TTL. Don't generate synchronously on request — even mid-sized trees take seconds.

Gotchas and Tips

• Encoding. GEDCOM is nominally UTF-8 (5.5.1) but real-world files are often ANSEL or Windows-1252. Garbled accents are the single most common support ticket. Detect and transcode on ingest; never trust the HEAD/CHAR tag alone.
• Line-ending and CONC/CONT. Long notes are split across CONC (concatenate) and CONT (newline) tags. If you persist note text without resolving these, your data is silently truncated. Resolve on read, re-split on write.
• Memory. Full-tree loads are fine for a few thousand individuals and not fine for a hundred thousand. Stream or chunk the reader for large imports and flush Eloquent relationships periodically.
• Custom Source binding (v8.6.0). The Source class is now container-resolved. If you previously monkey-patched or extended GedcomGenerator just to inject a custom Source, delete that workaround and register a binding instead. Note this is only a fix if you were relying on the old behaviour of a hard-coded new Source() — in which case a custom subclass you passed in may now need an explicit binding, so re-check any code where you constructed the generator with your own Source instance.
• Laravel 13. v8.6.0 fixes CI to allow Laravel 13, so the constraint is now permissive. That only proves the test matrix runs — validate your own app before upgrading a production install on Laravel 13.
• Extension points. The intended seams are the container (reader, writer, generator, and now Source), config, and subclassing on the generated objects. Avoid editing vendored files; the package moves quickly and you'll lose the diff.
• Debugging parse failures. The parser is usually permissive and skips unknown tags silently rather than throwing. If records are missing, log the raw line count before and after and compare against the TRLR terminator — a truncated file ends without it and parses "successfully" with half the tree.
• Concurrency. Two exports writing to the same filename will clobber each other. Namespace output paths per tree id and per timestamp.