Laravel Gedcom Laravel Package

Technical Evaluation

Architecture fit. cgdprojects/laravel-gedcom is a Composer-installed Laravel package that wraps GEDCOM parsing behind a service provider, config, and (presumably) a facade/API that returns structured individuals, families, and events. Architecturally it slots into an existing Laravel application as an ingestion library, not a service: one dependency, one config file, one adapter class. The correct boundary for a TPM to enforce is that the package owns parsing and nothing else. The canonical person/family model, deduplication and merge policy, source citations, media handling, privacy rules for living individuals, and audit trail all remain internal. If the package's record shape leaks into our domain model, we lose the ability to swap or fork it — and given the adoption signals below, that option must stay cheap.

Integration feasibility. Mechanically straightforward: composer require, publish config, wrap behind an internal GedcomImporter interface, map to our own DTOs. The actual cost is not the library — it is file validation, encoding handling, domain mapping, and the merge/dedup logic that GEDCOM imports always force. Planning estimate for one engineer: a 2–3 day spike to prove the parser against real-world files, then roughly 1–2 sprints for adapter, import pipeline, fixtures, and error taxonomy, plus QA time. That estimate assumes the package works; the spike exists to find out cheaply.

Technical risk. The dominant risk is longevity, not code quality. Signals: 22 stars (negligible adoption), a single visible release in the evidence set (2023-01-03), and no stated support policy. That is a thin maintenance base for a component on a data path that is expensive to replace late. Secondary risks, in order:

• Dialect and encoding coverage. GEDCOM 5.5.1 is the de facto standard; 7.0 exists but adoption is thin. Real files carry ANSEL/ASCII/UNICODE encoding declarations, BOM prefixes, mixed line endings, CONC/CONT continuation lines, and vendor-specific custom tags (_UID, _APID, etc.). The v3.4.3 "special characters" fix confirms this class of bug is live in the codebase and was recently being worked.
• Silent data loss. The worst failure mode is not a crash — it is a file that imports "successfully" while dropping unrecognized tags or individuals. Users discover this months later when their tree is wrong. We need an explicit policy: preserve unknown tags as raw payload, never discard silently.
• Laravel/PHP version drift. A package last released in early 2023 may not declare support for current Laravel/PHP majors. This is a hard gate, checkable in composer.json in minutes.
• PII and privacy. Uploaded family trees contain data about living people. Retention, deletion, consent, and GDPR posture are our problem, not the package's — but the import design must support per-record deletion and re-import.
• Untrusted input. User-uploaded files with unbounded size and structure. Needs size caps, timeouts, and isolation from request threads.

Evidence gap worth flagging. The assessment material provided reads as generic file-import boilerplate — CSV/Excel, delimiters, currency symbols, "catalog and pricing loads." None of it is GEDCOM-specific. A TPM should treat those documents as unvalidated for this package and not cite them in a go/no-go decision. The only package-specific facts we actually hold are: it parses GEDCOM for Laravel, MIT licensed, 22 stars, last release 2023-01-03, and that release fixed special-character import.

Key questions for the spike.

• What parser does it wrap internally, and is that maintained? (A wrapper around an abandoned parser inherits the abandonment.)
• Exact PHP/Laravel support matrix per composer.json and CI config — does it install cleanly on our target versions?
• GEDCOM versions and encodings covered — 5.5.1 only, or 7.0? ANSEL support?
• Behavior on unknown/custom tags: preserve, warn, or drop? Is there a hook to capture raw lines?
• Is parsing streaming/iterable, or does it materialize the whole tree in memory? What's the practical file-size ceiling?
• Test suite and fixtures — are there real-world vendor-dialect files, or only synthetic ones?
• Any open issues, CVEs, or security advisories? Any dependency with a known problem?
• Does it handle CONC/CONT, NOTE, SOUR citations, and multimedia references, or only the core individual/family/event graph?
• Who owns the fork if upstream goes quiet, and what's our patch-and-publish process?

Integration Approach

Stack fit. Native Laravel: Composer, service provider, config publish, and — if the parser is chunkable — queue jobs. No new runtime components, no new infrastructure, no new operational surface. That is the package's main strategic virtue: it converts a bespoke parser project into a dependency upgrade, which is a scope and headcount win a TPM can bank.

Migration path. Pin first, then prove, then adopt.

1. Pin the current version and run the spike on a branch against a fixture set of real GEDCOM files (Ancestry, MyHeritage, FamilySearch, Gramps exports, plus a hand-built edge-case file).
2. Install behind an internal GedcomImporter interface with the package confined to a single directory. No package types cross the boundary.
3. Persist the raw parsed payload first (JSON column) and normalize in a separate, replayable step. This makes a bad parser release recoverable by re-running normalization rather than asking users to re-upload — a cheap insurance policy that also gives us the audit trail we'll want later.
4. Pilot with internal users and one design-partner customer before general availability.
5. Rollback is a lockfile revert plus a re-run; no schema changes ride along in the adoption release.

Compatibility. Verify before committing: declared PHP/Laravel constraints vs. our versions; mbstring/iconv availability; utf8mb4 collation end-to-end; storage and upload limits; queue worker memory ceilings; and the GEDCOM version(s) our target users actually upload. Also confirm the MIT license and any attribution obligations are acceptable to legal — low friction, but it's a checkbox.

Sequencing. Gate the work so a bad outcome is cheap:

• Gate 1 (2–3 days): Spike. Does it install, parse our five real files, and preserve unknown tags? If no → build a thin internal parser or evaluate an alternative, and stop.
• Gate 2: Adapter + raw-payload persistence + fixture regression suite green.
• Gate 3: Pilot import with one real customer tree, validated person-by-person against the source file by someone who knows the data.
• Gate 4: General availability behind a feature flag.

Deliberately out of scope for the first release: merge/dedup across multiple files, incremental sync, and GEDCOM export. Those are product features with their own value case; bundling them would turn a two-sprint integration into a quarter and destroy the "buy not build" argument.

Operational Impact

Maintenance. Plan for a fork contingency from day one — vendor the package under our namespace or maintain a private fork, because the upstream release cadence is the single most likely thing to fail. Budget a small, recurring maintenance allocation (a few engineer-days per quarter) to watch the changelog, rebase the fork, and keep the parser green against new Laravel/PHP majors. Compare that to the fully-loaded cost of owning a GEDCOM parser in-house; if the fork overhead creeps toward that number, the build-vs-adopt thesis has failed and we should say so explicitly rather than drift.

Support. Support load is concentrated in file-encoding complaints ("my tree imported but the names are garbled," "half my family is missing"). Equip the help desk with: a sample-file capture requirement, an error taxonomy (unsupported encoding / malformed structure / too large / valid-but-unsupported tags), and a clear statement of which GEDCOM producers we support. Track import failure rate and partial-import rate as first-class product metrics, not just ticket volume — the partial-import rate is the one that predicts churn.

Scaling. Assume large trees (tens of thousands of individuals, tens of MB) and design for queued, chunked, resumable imports from the start. Synchronous in-request parsing will hit memory and timeout limits and will fail in a way that looks like user error. This is a design constraint on our wrapper, not a property of the package, and it is the most common place this kind of integration is under-scoped.

Failure modes to instrument. Malformed or truncated files; unsupported encodings (ANSEL being the usual offender); dropped custom tags; broken cross-references (individuals pointing at nonexistent families) and cyclic relationships; duplicate persons across re-imports without stable external IDs; DB collation mismatches mangling non-Latin scripts; memory/timeout kills on large files; and privacy leakage of living individuals into search or shared views. Each should have a counter, an alert threshold, and a user-facing message that distinguishes "we couldn't read your file" from "we read it but some records need review."

Ramp-up. The library itself takes an afternoon to learn. The scarce skill is GEDCOM domain knowledge — encoding declarations, continuation lines, dialect quirks, and what "correct" looks like for a genealogist. Budget one to two weeks for the implementing engineer to become genuinely effective, and require QA to work from real multilingual, multi-vendor fixtures rather than synthetic files. Capture that knowledge in the repo as fixtures and a short README, because with 22 stars and a single-maintainer upstream, our team is the only institutional memory this integration will have.