Php Dna Laravel Package

Getting Started

• composer require liberu-genealogy/php-dna — v4.0.0 is the current tag. There is no prior assessment, so pin ^4.0 explicitly rather than *; the v3→v4 jump is breaking (see Gotchas).
• Look first at the CsvReader entry point and the SNPs collection class. Both were patched in this release for duplicate declarations and syntax errors, which tells you they are the load-bearing classes and the ones to read before anything else.
• Minimal first use case: accept a raw DNA file upload, detect the vendor format, parse it into a SNPs collection, and persist rows keyed by (kit_id, rsid, chromosome, position).
• Check whether a service provider / config file is auto-discovered (php artisan vendor:publish). If the package exposes config for build numbers or vendor mappings, publish it early so you are not editing vendor code later.
• Sanity-check the install by parsing a small fixture file in a test before wiring it into a controller — the v4 changes touch parsing internals, so prove the happy path first.

Implementation Patterns

Upload → parse → persist (the core workflow). Store the uploaded raw file on a private disk, dispatch a queued job that streams it through CsvReader, and write SNPs in chunks. Never parse in the request cycle: real raw files are 15–30 MB and ~700k–1M lines.

// app/Jobs/ImportDnaKit.php
public function handle(): void
{
    $reader = new CsvReader($this->path);
    foreach ($reader->chunks(5000) as $chunk) {
        Snp::insert($chunk->map(fn ($s) => [
            'kit_id' => $this->kit->id,
            'rsid' => $s->rsid,
            'chromosome' => $s->chromosome,
            'position' => $s->position,
            'genotype' => $s->genotype,
        ])->all());
    }
}

Vendor format detection. Wrap vendor sniffing in your own small resolver (header line, comment prefix, column order) and store the detected vendor + genome build on the kit record. Do not re-detect on every read; the build number matters more than anything else downstream.

Kit-to-kit comparison. Treat comparison as a query, not a package call: join two SNP sets on rsid, filter to shared positions, and compute shared/opposing/no-call counts. This keeps you in Eloquent and lets you cache aggressively per pair.

Triangulation — you now own it. triangulateKits() was removed in v4.0.0 with no replacement. If you relied on it, reimplement the three-way logic yourself: find segments where A↔B and B↔C overlap on the same chromosome above a cM threshold, then intersect with A↔C. Model segments in a dna_segments table (kit_id, chromosome, start, end, cm, snp_count) and compute overlap with a range query. Persist segments once at import time so triangulation becomes a cheap join instead of a scan.

Visualization is a placeholder only. v4.0.0 adds a "visualization placeholder" alongside the removal. Do not build UI against it — treat it as a marker of intent. Keep chromosome-browser rendering in your own layer (e.g. a Livewire/Inertia component fed by your segments table) so future releases can't break your frontend.

Matching against third-party kits. Import external kits with a source flag so you can exclude them from user-facing counts and re-run comparisons after a re-import without touching the user's own kit.

Gotchas and Tips

• Breaking change in v4.0.0: triangulateKits() is gone. Any call site will fatal. Grep the codebase for triangulateKits before upgrading, and ship your own implementation (or a shim service) in the same PR. There is no deprecation path and no v3/v4 coexistence.
• Parser bug fixes mean behavior may change. v4.0.0 fixes duplicate method declarations and syntax errors in SNPs.php and CsvReader.php. Files that previously "worked" by accident — or failed loudly — may now parse differently. Re-run your fixture tests against real AncestryDNA, 23andMe, MyHeritage and FTDNA exports after upgrading, and diff row counts per kit.
• Genome build mismatch is the #1 silent bug. Build 37 vs build 38 positions are not comparable. Store the build per kit and refuse to compare across builds rather than producing confidently wrong matches.
• No-calls and haploid rows. -- genotypes, Y and MT chromosomes, and single-allele calls will break naive pairwise genotype comparisons. Normalize on import; decide explicitly whether -- counts as a mismatch.
• Memory. Prefer the streaming/chunked API over any method that returns the full SNP set. A collection of a million small objects will exhaust the default 128 MB limit; chunk()/generators are the escape hatch.
• Indexing. Composite index on (kit_id, rsid) plus (kit_id, chromosome, position) — comparisons and segment queries both depend on it. Without it, every match is a full scan.
• Debugging parse failures. Log the offending line number and the raw line (redact the genotype if it is user data) — CSV parsing errors in this domain are almost always an unexpected header row, a trailing comment block, or a CRLF/encoding quirk.
• Extension points. Favor wrapping the package behind your own DnaImporter / KitMatcher services rather than calling it from controllers. Given the pace of breaking changes here (removal in a single minor bump), an anti-corruption layer is what keeps the next upgrade cheap.
• Version discipline. Pin exactly, upgrade deliberately, and keep a fixture-based regression suite. Two releases in and the package has already removed a public method and shipped parser fixes from a new contributor and an automated agent — treat every tag as potentially breaking until proven otherwise.