Importer Laravel Package

Technical Evaluation

Architecture fit. Statamic Importer is a first-party addon that plugs into the CMS's own content model rather than running alongside it. Importer definitions are PHP classes living in the application repo, registered through the published config, mapping a source (CSV, JSON, XML, Eloquent) onto a collection destination with per-field transforms. That makes import logic a versioned, reviewable artifact instead of an ad-hoc script — the single most important property for a migration that has to be re-run, audited, and eventually handed to someone else.

The scope is deliberately narrow: one-directional landing of external rows into entries. It is not a sync engine, and any requirement that looks like CDC, two-way reconciliation, or cross-entry computed fields is out of remit and should be scoped as custom code, not stretched configuration.

Integration feasibility. Install is a single composer require statamic/importer:^2.3.2 plus vendor:publish. The real work is upstream of the package: the target collection and blueprint must already exist as file-based definitions, and every field referenced in a mapping must already be defined on the blueprint. The importer does not create field definitions. Driver breadth (csv, json, xml, eloquent) covers the usual migration shapes; the Eloquent driver is the decision-relevant one because it removes the export-to-CSV intermediate step and lets a parallel-run period read straight from the legacy database.

Technical risk. Three risks dominate, in order:

1. Silent partial success. The default failure mode is a run that reports success at the row-count level while relationships are empty. Issue #148 — related entries not resolving under the Eloquent driver — is exactly this, and it is why 2.3.2 is the floor. Row counts are not verification; relation-level assertions are.
2. Thin adoption. 18 stars and zero dependents means no community knowledge base to budget for. Mitigants: first-party status, active issue tracker, named contributors. The vendor source is the documentation, and the plan should fund reading it.
3. API drift within 2.x. Method names and even the run command have shifted across minors. Trust the installed abstract Importer class and artisan list output over any published example, including our own onboarding notes.

Secondary risks: CSV type coercion (empty string is not null), slug collisions, fieldtype-specific payload shapes (Bard/Replicator/Assets need structured JSON, not raw HTML strings), and staleness of search indexes, Stache and static caches after a write.

Key questions to close before committing a date:

• Which blueprint fieldtypes are in scope for the first import, and are they supported without custom transforms? This is the spike, not the install.
• Where does the stable external unique key come from, and is it guaranteed populated on every source row?
• Which queue worker will pick up import jobs, and does its timeout and memory limit tolerate the largest batch?
• Is the legacy source reachable via a dedicated read-only connection, or does it require an export step after all?
• Single-site or multisite at launch; if multisite, is there a per-site unique key?
• Does the launch plan require a parallel run, and therefore re-imports against a live legacy system?
• Who is the named internal owner of importer definitions and their regression tests?

Integration Approach

Stack fit. The package targets Statamic 4/5 on Laravel 10/11/12 with PHP 8.1+. It installs into the existing application — there is no sidecar service, no separate deployment unit, and no new operational surface beyond the queue that already exists. That is a meaningful procurement advantage: it can be adopted incrementally without an architectural commitment.

Migration path. Sequence it as discovery, not as build:

1. Install and publish config; pin ^2.3.2 and confirm the exact Statamic/Laravel/PHP matrix against the addon's composer.json before investing build time.
2. Model the target collection and blueprint in files under version control.
3. Build a five-row fixture importer against a hand-written CSV — not a real extract. The point is to exercise the shape, not the volume.
4. Run it once through the Control Panel, upload-preview-map-run, to observe the review and error-reporting screens the content team will actually use. This is what determines whether content ops self-serve or the app team owns every run.
5. Write the relation-level test before scaling volume.
6. Move to the real source, then to queue-backed batch runs in staging.
7. Production, with the idempotent key verified by running twice.

Compatibility and upgrade handling. Treat 2.3.2 as a data event, not a dependency bump. On any project already carrying Eloquent-sourced relations, the sequence is: drain the queue, deploy, re-import affected content under the same idempotent key, and diff relations before and after. Retire any manual post-import patch script deliberately and in the same window — leaving both the workaround and the fixed resolution logic running double-applies corrections.

Sequencing constraints. Anything order-dependent needs two passes: categories before products, authors before articles, parents before children. Statamic entries fields require the target entry to exist; a forward reference writes null silently. Run parents, verify, then children. Relations should resolve through a map preloaded once before the import and closed over in the transform, never a per-row lookup.

Exit and reversibility. Because the importers are config-as-code and re-runnable, the cost of leaving Statamic later is bounded. Worth stating explicitly whenever lock-in comes up: the same artifacts that make migration in cheap make migration out cheap.

Operational Impact

Maintenance. Budget for internal ownership from day one. Importer classes should be reviewed in PRs like migrations, named for the source system, and parameterised on source path or model rather than the file someone happened to import. Each one needs a fixture test asserting field values and relation IDs. The thin dependency graph means no upstream community to lean on when something breaks — the vendor source is the reference, and the plan should assume an engineer reads it.

Support model. The CP pass in the integration plan is the gate: if content ops can drive upload → preview → map → run and interpret the error reporting, they own routine imports and the app team owns definitions. If not, the app team owns every run and that cost recurs on each content cycle. Decide this explicitly rather than discovering it after launch.

Scaling. Imports dispatch as queued jobs. Constraints that matter at volume: worker --timeout and memory_limit sized to the largest batch; explicit column selection on Eloquent sources (a wide legacy table with * will exhaust memory on a chunked run); transforms kept free of database or HTTP lookups, which turn a four-minute import into a forty-minute one through N+1 access. Don't run a large import from the CP on a shared queue without knowing which worker picks it up.

Failure modes to instrument and put in the runbook:

• Silent partial success — relations empty while row counts pass. Mitigation: mandatory spot-check of an entry with a known related record, stated in those words on the content-ops sign-off checklist.
• Duplicate entries on re-run when no stable unique key is declared on the destination.
• Type coercion — empty strings landing in nullable date fields, booleans arriving as "1"/"true"/"Yes", numbers with thousands separators.
• Slug collisions — two entries titled "About" collapse into one with an unexplained override; drive slug from the unique key.
• Unsupported fieldtypes — Bard, Replicator and Assets require shaped payloads and, for assets, a container, a file on disk and a matching path.
• Stale derived state — search index, static cache and Stache are not invalidated by an import. The first editor ticket after any run is "the new products don't appear in search."
• Multisite drift — an unset site means the default site; localised content needs one run per locale.

Ramp-up and cost. Roughly 1–2 developer days for a first non-trivial importer with relations, plus a validation pass with content ops, plus a half-day fieldtype spike against the real blueprint. Marginal cost per additional source shape is low once the pattern and tests exist. The business case should be priced against the lifetime cost of the in-house Artisan command alternative — every legacy schema or content-model change — not against that script's first version. The same logic applies to roadmap: content import sits on the critical path to relaunch, so any spike it needs belongs in the plan before design freeze, not discovered during build.