Importer Laravel Package

Product Decisions This Supports

• Replatform / CMS migration go/no-go. Import tooling is the biggest single variable between "moving to Statamic is a scoped, repeatable project" and "it's a bespoke engineering effort." This package is that variable, so it belongs in the business case — estimated during discovery, not discovered mid-build.
• Build vs. buy on migration tooling. The credible alternative is an in-house Artisan command plus a mapping layer we own and maintain forever. Price that against lifetime cost (every legacy schema shift, every content-model change, every new source), not first-version cost. This package shifts the work from "write a script" to "declare configuration," which is a different maintenance burden.
• Source-data strategy. The Eloquent driver is the decision-relevant capability: imports read directly from the legacy relational database rather than requiring an export-to-CSV handoff. That moves ownership of migration from content ops to the app team and makes repeat imports cheap enough to run as a sync during a parallel run instead of a single cutover.
• Rollout strategy: phased / parallel-run vs. big bang. Because importer definitions are versioned, config-driven artifacts, we can migrate in batches, verify against the old system while both run, and re-run after fixes. That is a materially lower-risk launch plan — and one we can only credibly commit to if imports are re-runnable.
• Content-model boundary: Statamic vs. application database. The package supports a clean split — editorial content in Statamic, reference/master data stays in app tables and is pulled in. Make the boundary explicit so "the CMS is our database" doesn't drift in later at high unwind cost.
• Idempotency as a product requirement, not a technical detail. Every importer needs a stable external unique key (SKU, legacy ID, slug) so re-runs update rather than duplicate. Without it, the second run creates duplicates and the parallel-run plan collapses. This is a sign-off item, not a developer nicety.
• Version floor as an explicit decision. v2.3.2 fixes related entries not resolving under the Eloquent driver — a silent partial success where entries look complete but relationships were never written. Any plan leaning on database-sourced relations treats 2.3.2 as the floor, and treats the upgrade as a data change, not a dependency bump: previously imported content needs re-import and a before/after relation diff.
• Ecosystem-risk sizing. Adoption is thin (18 stars, 0 dependents), so there is no community knowledge base to budget for. Mitigants: first-party Statamic addon, active issue tracker, named contributors. Plan for named internal ownership of importer definitions and their regression tests before migration becomes load-bearing for a launch date.
• Fieldtype coverage as an unquantified scope risk. Bard/Replicator/Assets fields need structured input, not raw CSV columns. Timebox a half-day spike mapping our real blueprint against a fixture and write down what's unsupported — that output feeds the estimate, not a later surprise.
• Launch-readiness gate. An import writes entries; it does not reindex search, clear static caches, or warm Stache. Unless those follow-ups are in the runbook as part of the import, the first thing an editor reports on day one is "the new content doesn't show up." Treat post-import cache/index steps as product acceptance criteria.
• Exit and reversibility planning. Re-runnable, config-driven imports lower the future cost of leaving Statamic. Worth stating explicitly whenever "are we locking ourselves in?" comes up with leadership.
• Explicit out-of-scope line. Continuous two-way sync, change-data-capture, and cross-entry computed fields are beyond this package's remit. If those appear in requirements, that's a separate build decision — and the honest exit is a thin custom command for the 10% the importer can't express, not ever-more-elaborate transform closures.

When to Consider This Package

Good fit:

• You are migrating into Statamic (v4/v5) and the source is CSV, JSON, XML, or a legacy relational database reachable via Eloquent.
• The target collections and blueprints exist or can be defined and version-controlled in files first — the importer does not create field definitions.
• Content arrives in identifiable passes (categories before products, authors before articles), so a two-pass, order-dependent import is workable.
• You want content ops to self-serve routine imports via the Control Panel, with developers owning the definitions — the CP review-and-error workflow is a real adoption factor, not a demo feature.
• Re-runnability matters: parallel runs, staged cutover, or repeat imports after fixes.
• The target fields are predominantly text, numbers, dates, slugs, and relations.
• You can run and observe a queue worker (Horizon or queue:work) with timeouts and memory limits sized to your largest batch.

Look elsewhere or plan a custom layer when:

• You need continuous two-way sync, change-data-capture, or field values computed across entries — that's a sync engine, not an importer.
• The source is an API with pagination, auth refresh, and rate limits; there's no first-class driver, so you'd be writing one anyway.
• Your blueprint leans heavily on Bard/Replicator/Assets and you haven't done the fieldtype spike — confirm coverage before committing a date.
• Multisite localised imports without a clean per-site unique key — the package will land entries in a site (default if unset), but the correctness burden is yours.
• You cannot name an internal owner for importer definitions and regression tests. Thin adoption plus zero dependents means no community answers; unowned configuration becomes load-bearing and fragile.
• The team expects a UI-only, no-code tool. This is a developer-authored configuration surface with a CP front end, not a connector marketplace.
• Volume is very large with wide legacy tables — select explicit columns and chunk deliberately, or memory will be the limit rather than the tool.

Adoption checklist (order matters): confirm the version matrix and pin 2.3.2+ → stand up a five-row fixture before a five-thousand-row migration → create importer class under app/Importers, register in config → run once through the CP to validate the review/error UX → add a fixture test asserting field values and relation IDs, not row counts.

How to Pitch It (Stakeholders)

For executives — one paragraph. Relaunching on Statamic requires moving our existing content, and that migration is the part most likely to blow a timeline. This is Statamic's first-party import addon: it turns migration into versioned configuration files instead of a one-off script, which lets us migrate in verifiable batches, re-run imports safely after fixes, and keep the old system running alongside while we check results. That converts the highest-risk item on the relaunch plan from a big-bang cutover into a staged, reversible rollout. The costs are a day or two of Laravel developer time for the first real importer, a validation pass with content ops, and one named internal owner. The risks are known and bounded: a thin user community (no outside answers to lean on — mitigated by first-party support), a required minimum version that fixes a silent relationship-import bug, and a fieldtype coverage check we should timebox before committing a date.

For engineering leads. Treat importer definitions like migrations: named for the source system, reviewed in PRs, re-runnable in staging, parameterised rather than hard-coded to today's file. Require an external unique key on every destination so re-runs update rather than duplicate. Keep transforms simple and pure — anything needing a DB lookup or HTTP call becomes a second pass, with relation lookups preloaded into a map before the run. Queue the work, know which worker will pick it up, and size timeouts and memory to the largest batch. Verify at the relation level with a fixture test; row counts are not verification, because the known failure mode here is silent partial success — rows present, relationships empty. Pin 2.3.2 or above, and when upgrading, plan a drain-deploy-reimport-diff sequence and consciously retire any manual post-import patch script rather than leaving both paths running. Add search reindex, static cache clear, and Stache warm to the runbook as part of the import.

For content operations. You'll get a Control Panel workflow — upload, preview, map, run — with progress and error reporting, and a CLI path for scheduled or bulk runs. Two asks of you: spot-check related content on a sample entry after every meaningful import (that's the sign-off wording, deliberately — scalars pass while relations silently don't), and expect messy source data to be normalised, not guessed at: empty strings, "1"/"yes " booleans, and thousands separators are handled by explicit mapping rules we agree up front. Slugs are driven from the unique key so two similarly titled entries can't quietly overwrite each other. Multisite imports run once per locale with the site set explicitly.