Migrator Laravel Package

Technical Evaluation

What this actually is — settle this first. The description is unambiguous: this is a one-shot content importer for Statamic v2 → v3, not a versioned schema-as-code migration tool. The competing reading in circulation (Laravel-style, reversible, rollback-able content-structure migrations) is a materially different product with a different lifetime and a different adoption plan. Treat the broader schema use case as unverified until the command surface is read. A half-day spike settles it: src/ServiceProvider.php, then src/Console/. Whether commands register under php please or php artisan is the tell. Until then, the documentation ambiguity is itself a risk finding — a first-party tool whose scope is contested in its own README is a tool whose behavior you verify rather than assume.

Architecture fit — low by construction, because there is no runtime footprint. The package operates on flat files: reads a v2 content tree, transforms, writes into a fresh v3 install. It never sits in the request path, never owns a database table, never serves a page. That means near-zero production blast radius and near-zero architectural coupling. It also means it is not infrastructure — it belongs on a throwaway migration branch in require-dev, pinned to an exact version, and should be deleted after cutover. The only scenario where that changes is if the spike proves the schema-migrations reading, which would make this a permanent architectural commitment requiring an explicit written decision (migrations as source of truth vs. Control Panel edits — pick one).

Integration feasibility — gated entirely by the version matrix, not by engineering effort. This tool exists to bridge one specific major-version pair. If you are not on v2 and not targeting v3, feasibility is zero and no amount of configuration changes that. If you are, the work is mapping work, not tooling work: fieldsets, custom fieldtypes, addon-owned data, globals/navs, forms, drafts and revisions, multisite/localization directories, asset metadata and focal points. The tool converts the mechanical copy into a configured run; the intellectual labor of deciding what "correct" means remains yours. Budget the counterfactual — roughly 2–6 engineer-weeks of bespoke ETL plus QA — as the business-case anchor, and treat the tool as compressing the mechanical share of that, not the whole of it.

Technical risk.

• Hard version gate. v2 and v3 are both legacy: PHP 7.x-era, Laravel 5.x/6.x-era toolchain. If the source site has drifted onto a patched PHP or carries custom addons, the window closes fast. Confirm from composer.json in week one — fork, bespoke ETL, or stop.
• Coverage gaps are the default, not the exception. Globals, navs, forms, revisions, drafts, multisite, SEO/redirect addons, and custom fieldtype reference data are the classic silent-loss surfaces. Absence of errors is not evidence of presence.
• No transactional rollback for data. down() is not a true inverse of content writes. Snapshot-based restore is the real rollback path.
• Destination is also stale. v3 is not current. This is hop one of a ladder, not an arrival. Whether the emitted v3 content model cleanly feeds the vendor's v3→v4/v5 upgrade path is the single question that determines whether this tool saves a hop or just moves the same problem one version forward.
• No community QA. 43 stars, zero dependents: no blog posts, no Stack Overflow answers, no crowd to ask. First-party provenance is a genuine maintenance signal — escalate it through any Statamic support agreement — but it is not an SLA. You are the QA.

Key questions to answer before scoping.

1. Which command surface does it register — please, artisan, or both?
2. Does it emit a v3 content model that the current upgrader chain accepts?
3. What is explicitly out of scope: globals, navs, forms, revisions, multisite, user passwords, asset metadata?
4. Does it chunk or batch large asset libraries, and is it safely re-runnable as a delta?
5. Who patches it if it falls short — and is the package small enough to fork (likely yes)?

Integration Approach

Stack fit. Laravel + Statamic v2 source, Statamic v3 target, PHP matching the package's declared matrix. No fit with a modern stack, and no fit with a non-Statamic source. Validate the matrix against your real toolchain at spike time, not at cutover.

Migration path — it is a ladder, and this is only the first rung. Frame it explicitly: v2 → v3 via this tool, v3 → v4/v5 via the vendor's own upgrade route. The adoption decision therefore hinges on the second hop. If the v3 output is upgrade-ready, this buys a cheap, reversible first step and unlocks supported versions and security patches sooner. If it is not, the plan is a time-boxed full re-platform and this tool is a partial accelerant for the content subset only. Either way, the decision is upgrade vs. rebuild vs. stay, and the tool's job is to make that decision cheap to answer.

Compatibility. Pin the exact version. Read composer.json for PHP/Laravel/Statamic constraints and any extension requirements. Check whether custom fieldtype handlers are registered by the package or expected to exist on the target. Confirm behavior against a fresh, empty v3 install rather than an existing one — a pre-populated target muddies every subsequent diff.

Sequencing.

1. Spike (½ day, isolated branch). Resolve scope identity; read service provider and console commands; publish and read config.
2. Compatibility gate. Matrix match yes/no. If no, stop and re-plan — do not proceed on hope.
3. Throwaway target. Clean v3 install, source paths configured.
4. Pilot subset. One collection, a handful of entries, a sample of assets. Verify counts, relationship integrity, and rendered pages — not just file presence. php please stache:clear before concluding anything is broken or working.
5. Written go/no-go against pilot findings: coverage gaps enumerated, each with a workaround or an accepted loss.
6. Full run, then delta re-run immediately before cutover, behind a short content freeze.
7. Verify, checkpoint, cut over. Snapshot content/, users/, resources/blueprints/, resources/fieldsets/ before every non-trivial run.
8. Retire the tool — merge nothing, delete the branch, or promote to require-dev on a preserved tag purely for auditability.

Order content by dependency, not by convenience: users and roles first, then taxonomies, then assets, then entries. If the tool's internal ordering is fixed, verify it matches — a reference migrated before its target is a broken link you will find on a rendered page later, not in a log.

Operational Impact

Maintenance — near zero, by design, if you use it as intended. One run, verification, done. The only maintenance burden is the delta window and whatever patches you carry. Keeping it out of require removes it from dependency churn entirely. The permanent-tax failure mode appears only if you adopt the schema-migrations reading: then Control Panel structural edits silently desynchronize the migration files, and the cost compounds for years. Decide in writing and stick to it.

Support. First-party, no SLA, effectively no public validation. Escalate through your Statamic commercial relationship; expect guidance, not guaranteed fixes. Budget for an internal fork — the package is small enough that forking is a realistic line item rather than a threat. Assign a named owner for the migration branch so the fork doesn't become orphaned code.

Scaling — content volume, not traffic. Runtime and failure windows scale with entries, assets, and files; the constraint is verification throughput, not the tool. On a large asset library, budget for chunking, batch verification, and a human reviewing samples. Plan the schedule around reviewer capacity — that's the real bottleneck in the pilot-to-full-run gate.

Failure modes to plan for.

• Partial writes on interrupt — no transaction boundary; re-runs land in an unknown state unless the tool is idempotent. Verify re-runnability explicitly.
• Silent field drops — custom fieldtypes copy the value but not the reference; the field looks populated and the page renders wrong.
• Draft/revision/localization loss — these live alongside entry content and are the quietest casualties. Check each locale directory has its entries.
• Stache drift — false negatives that burn a day. Clear and warm before any conclusion.
• CP drift — only if misadopted as permanent schema tooling.
• Version window closing mid-project — the target v3 install itself goes out of support while you migrate to it.

Ramp-up. Requires someone fluent in blueprints, fieldsets, the Stache, and Laravel console tooling — this is a staffing decision, not a composer require. Realistic allocation: one engineer-day to read the source and produce a credible command-surface map; roughly one engineer-week to map a non-trivial content model and enumerate gaps with workarounds. Debugging discipline is cheap and high-yield: -vvv on every command, one step at a time rather than whole batches, git diff on content/ and resources/ after each step, and a clone of the pre-migration site to diff against. When something looks wrong and the cache is clear, read the emitted YAML directly rather than through the Control Panel.