Php Dna Laravel Package

Technical Evaluation

Architecture fit liberu-genealogy/php-dna is a domain library in the Liberu genealogy ecosystem, responsible for DNA/SNP data handling (SNP parsing, CSV ingestion) inside Laravel applications. It is a Composer-installed dependency rather than an application, so architectural coupling is low — the main coupling points are the public class API (SNPs, CsvReader, and the recently removed kit-triangulation surface) and whatever service-provider bindings ship with the package. It fits as a library behind an application service layer, not as something to build directly against in controllers or jobs.

Integration feasibility Feasible via a normal composer require major-version bump, but v4.0.0 is not a drop-in upgrade. Two changes drive the assessment:

• Breaking removal: triangulateKits is deleted, not deprecated. Any consumer calling it will fail at runtime (BadMethodCallException/undefined method), not at install time — the most expensive failure shape because CI can pass while production breaks.
• Reliability fixes: PR #169 fixes duplicate method declarations and syntax errors in SNPs.php and CsvReader.php. Positive on its face, but it implies shipped v3.0.0 code had parse-level defects in core files. Duplicate method declarations and syntax errors are exactly what php -l and a test suite catch, so this is evidence of weak CI gating upstream, not just a one-off bug.
• Placeholder feature: the "visualization placeholder" is presumably a stub. It should not be treated as a delivered capability or planned against.
• Provenance signal: both PRs come from first-time contributors, one of which is @Copilot. AI-assisted fixes are acceptable, but combined with a major-version breaking removal released in the same two-PR window, it warrants a deeper review before adoption.

Technical risk Overall: medium-high for v4 adoption, medium for staying on v3.

• Highest risk is undetected triangulateKits call sites, especially anything exercising DNA kit triangulation — a core genealogy workflow, so probability of use in a downstream genealogy app is meaningful.
• Secondary risk is recurrence of parse/duplicate-method class defects if upstream gating is unchanged.
• The placeholder creates ambiguity risk: stakeholders may assume a visualization capability exists.

Key questions

1. Which downstream services (including Liberu's own application) call triangulateKits, and what is the sanctioned replacement — a new package, an application-level implementation, or nothing?
2. Is the visualization placeholder exposed on the public API or behind a flag, and does it return a safe empty value or throw?
3. Did the PHP and Laravel version constraints change between v3.0.0 and v4.0.0? Release notes are silent.
4. Was v3.0.0 actually broken on autoload of SNPs.php, or were those code paths unreachable? This determines whether v4 is a fix or a stabilization of dead code.
5. What is upstream's test coverage and CI lint posture, and is there a commitment to keep php -l/static analysis in the pipeline?
6. Is there a support window for v3.x, or is the removal immediate with no backport of the syntax fixes?

Integration Approach

Stack fit Standard Laravel/PHP + Composer consumption. Confirm the supported PHP/Laravel matrix before scheduling work — the release notes do not state constraint changes, and a major bump is the most common place for a silent composer.json requirement shift. Verify against our oldest supported PHP runtime, not just the developer's local version.

Migration path

1. Inventory before upgrade. Grep the application and all internal packages for triangulateKits, plus direct references to SNPs and CsvReader. Include dynamic calls (call_user_func, string-based method names) and any queued jobs or artisan commands that touch DNA kits.
2. If triangulateKits is unused: upgrade is low-risk; proceed on a branch and validate parsing paths.
3. If used: do not upgrade yet. Either (a) stay pinned to v3.x and cherry-pick the SNPs.php/CsvReader.php fixes as a vendored patch, or (b) implement triangulation in the application layer before bumping. Option (a) is the faster unblock if v3 parsing is actively failing; option (b) is the durable fix.
4. Pin explicitly ("liberu-genealogy/php-dna": "^4.0" or "^3.0") rather than floating, given the release cadence.

Compatibility checks

• Run php -l and static analysis (PHPStan/Psalm at our configured level) against the installed vendor tree immediately post-upgrade — v4's own history shows parse-level defects can ship.
• Execute the existing CSV/SNP fixture suite and diff parsed output against v3 baselines. Fixing duplicate methods can change which implementation wins at runtime; identical-looking input may now produce different output if the previously-shadowed method was the effective one.
• Confirm no downstream code extended or reflected on the removed method.

Sequencing Phase 1 — usage inventory and constraint verification (no code change). Phase 2 — branch upgrade with lint + static analysis + fixture regression. Phase 3 — staging canary against real DNA kit files, including at least one oversized file to exercise memory behavior. Phase 4 — production rollout behind the existing release mechanism; keep v3 revert path warm for one cycle. Explicitly exclude the visualization placeholder from scope and from any roadmap communication until it is functional.

Operational Impact

Maintenance Small contributor base with ad hoc cadence; this release ships a breaking change, two reliability fixes, and a placeholder in a two-PR window. Budget recurring effort for reading upstream diffs rather than assuming semver discipline — commit-level review is justified here. If triangulation is business-critical, plan to own that logic in-application so future upstream removals cannot block us.

Support No evidence of an LTS policy or a v3.x maintenance branch. Escalation path is the upstream issue tracker with limited leverage; mitigate by vendoring/patching critical files locally (which we can do under MIT-style licensing — verify the license) and documenting the patch so it is re-applied deliberately rather than silently lost on the next composer update.

Scaling SNP and CSV ingestion is CPU- and memory-bound. Raw consumer DNA files run into the hundreds of megabytes; the relevant question is whether CsvReader streams or loads fully into memory. Given that CsvReader.php was just repaired, re-benchmark rather than assume inherited performance characteristics. Run parsing in queued jobs with memory limits set deliberately, not on web requests.

Failure modes

• Runtime fatal on class load — the exact shape of the pre-v4 defect; mitigated by lint/static analysis in the pipeline and a smoke test that autoloads SNPs and CsvReader.
• Call to removed triangulateKits — silent through CI, loud in production; mitigated by the usage inventory.
• Behavioral drift from the duplicate-method fix — passes tests, changes output; mitigated by fixture diffing.
• Placeholder mistaken for a feature — a caller gets an empty visualization and treats it as data loss; mitigated by keeping it out of scope and off the roadmap.
• Unpinned version resolving to an unexpected v4.x — mitigated by explicit constraints plus a lockfile.

Ramp-up Low technical ramp-up: the package surface is a handful of classes and a PHP developer is productive in roughly one day. The real cost is domain QA — validating that parsed SNPs and ingested CSVs are genetically correct, not merely non-crashing. Budget one to two engineering days for integration plus a QA pass with real kit data, and add one day if triangulateKits turns out to be in use and must be reimplemented in-application.