Php Gedcom Laravel Package

Technical Evaluation

Baseline note: No prior assessment existed for this package; this is the first formal evaluation and it reflects v4.2.0 as the reference version.

Architecture fit

• liberu-genealogy/php-gedcom is a domain-specific parser/serializer for GEDCOM and now GEDCOM-X. In a Laravel codebase it is a library-layer dependency, not an application framework concern — it should sit behind an adapter/service class in our domain layer rather than being called directly from controllers or Eloquent models.
• v4.2.0 adds two capability surfaces: (1) GEDCOM → GEDCOM-X mapping, explicitly marked WIP/partial, and (2) UID/_UID handling across all record types with GEDCOM-X export. The UID work is the more architecturally significant of the two, because stable record identity is what makes idempotent import/re-import, deduplication, and cross-system reconciliation tractable.

Integration feasibility

• Composer-installable, minor version bump (4.1.1 → 4.2.0) implies semver-compatible and additive. Low integration friction for existing parse/write paths.
• GEDCOM-X output is JSON-shaped and maps naturally onto Laravel JsonResource responses if we expose it via API, which reduces bespoke serialization work.
• The mapping layer being WIP means we should treat GEDCOM-X export as an experimental capability gated behind a config flag rather than a supported product surface.

Technical risk

• AI-authored changes. Both PRs in this release are attributed to @Copilot, including one still marked [WIP]. A first-time automated contributor landing a cross-cutting "all record types" change is a review-depth risk: broad surface area, thin provenance. Assume human review was light until we verify otherwise.
• Semantic drift. "UID/_UID support for all record types" is a strong claim. GEDCOM 5.5.1 and GEDCOM-X treat identifiers and _UID custom tags differently; a bulk addition can silently change round-trip fidelity (parse → emit → parse).
• WIP merged into a release. A [WIP]-labelled PR shipping in a tagged minor version signals weak release gating. Expect behavioural changes in the mapping layer in future patch releases.
• No published migration or configuration notes in the release body — unclear whether new behaviour is opt-in or default-on.

Key questions

1. Is UID emission/consumption default-on or behind config? Does it alter output for existing GEDCOM writers?
2. Which GEDCOM-X entities are actually implemented vs. stubbed in the mapping layer?
3. What is the test coverage for the new record-type paths, and was a human reviewer of record involved?
4. Are _UID values preserved verbatim on round-trip, or normalised/regenerated?
5. Licensing/attribution position on AI-generated contributions in a dependency we redistribute or vendor.

Integration Approach

Stack fit

• Laravel 10/11 + PHP 8.x; integrate as a Composer dependency wrapped by an application-owned GedcomGateway interface so the package can be swapped or pinned without touching domain code.
• Import/export should run as queued jobs (ImportGedcomJob, ExportGedcomXJob) writing to a configured filesystem disk, not synchronously in request cycles.

Migration path

• Pin 4.2.0 explicitly and start on a feature branch with the GEDCOM-X export path disabled by default.
• Establish a golden-file regression suite first: a corpus of representative GEDCOM files parsed and re-emitted on 4.1.1, then diffed against 4.2.0 output. This is the cheapest way to detect UID-induced round-trip changes.
• If diffs are material for existing users, remain on 4.1.1 for write paths and consume 4.2.0 read-only until validated.

Compatibility

• No deprecations or breaking changes signalled by the minor bump; assume backward compatibility for the classic GEDCOM parse/write API.
• GEDCOM-X mapping should be treated as pre-stable regardless of semver, given the WIP label.

Sequencing

1. Add dependency at 4.2.0 behind adapter + config flags; no behavioural change.
2. Run golden-file round-trip suite; record diffs attributable to UID handling.
3. Enable UID read/preserve only. Validate identity stability across repeated imports.
4. Pilot GEDCOM-X export against one downstream consumer (e.g. FamilySearch-style JSON) in a non-production environment.
5. Promote GEDCOM-X export to supported only after the mapping PR leaves WIP and we have coverage evidence.

Operational Impact

Maintenance

• Small-maintainer, single-repository project in the Liberu genealogy ecosystem; release cadence appears PR-driven rather than scheduled. Budget for us to carry patch-level forks if upstream stalls.
• The Copilot-authored contribution pattern suggests future releases may require more upstream scrutiny than a typical dependency — assign a named owner to review each release note before upgrading.

Support

• Community support only; no vendor SLA or LTS branch. Escalation path is opening issues upstream plus internal workaround ownership.
• We must be able to operate the 4.1.1 pin for an extended period; keep the adapter boundary clean enough to allow this.

Scaling

• GEDCOM files are frequently tens to hundreds of MB and genealogies can be deeply nested — memory ceiling is the primary scaling concern. Enforce streaming/chunked parsing in jobs, cap file size at upload, and set job timeouts and memory limits explicitly.
• GEDCOM-X output is JSON and can be substantially larger than source GEDCOM; plan object-storage retention and API pagination if export is exposed to end users.

Failure modes

• Malformed or non-conformant GEDCOM (encoding mismatches, ANSI vs UTF-8, custom _ tags) → parse exceptions; needs per-record error isolation and a partial-import report rather than all-or-nothing failure.
• UID collisions or regeneration → duplicate person records on re-import; mitigate with an idempotency key on import and reconciliation reporting.
• Incomplete GEDCOM-X mapping → silently dropped fields in export. Detect via round-trip/field-count assertions, not user reports.
• WIP mapping changes in a future patch → output shape drift; pin exact versions and re-run golden files on every bump.

Ramp-up

• Low learning curve for the classic GEDCOM API; moderate for GEDCOM-X, since the package does not yet document its mapping coverage.
• Ramp estimate: ~1 day for a Laravel developer to integrate parse/write behind the adapter; ~3–5 days to build the golden-file suite and validate UID identity behaviour; GEDCOM-X export should be scoped as a spike, not committed work, until the WIP mapping stabilises.