Weave Code
Importer Laravel Package
statamic/importer
Statamic Importer brings external data into Statamic collections from CSV, JSON, XML, and other sources. Map fields, transform values, preview results, and run repeatable imports from the control panel or CLI.
Statamic Importer is a first-party addon that brings structured data into your Statamic site from CSV, JSON, and XML sources. It provides a Control Panel workflow for uploading a file, mapping source columns to collection fields, and previewing results before committing—so large migrations and routine content syncs happen without hand-written scripts.
- Field mapping from source columns to any collection fieldtype
- Dry-run preview to validate rows before import
- Extensible importers for custom formats and transformations
- Runs via Control Panel or Artisan commands
- Works with multisite and localized content
Frequently asked questions about Importer
- What is statamic/importer used for?
- Statamic Importer is a first-party addon for bringing structured data from CSV, JSON, XML, and Eloquent sources into Statamic collections. You upload or point at a source, map columns to blueprint fields, preview rows, and then commit the import from the Control Panel or Artisan. It is designed for migrations and repeatable one-directional imports rather than ongoing two-way sync.
- How do I install statamic/importer in a Laravel application?
- Install it with composer require statamic/importer:^2.3.2 and publish the config with vendor:publish. The target collection and blueprint must already exist as file-based definitions before the import runs, and every field in the mapping must already be defined on that blueprint. The package does not create field definitions for you.
- Which Statamic, Laravel, and PHP versions does statamic/importer support?
- The addon targets Statamic 4 and 5 on Laravel 10, 11, and 12 with PHP 8.1 or newer. Confirm the exact matrix against the addon's composer.json before planning build time. Pin ^2.3.2 because method names and the run command have shifted across 2.x minors, and 2.3.2 includes the fix for related entries not resolving under the Eloquent driver.
- What source formats can Statamic Importer import from?
- The built-in drivers cover csv, json, xml, and eloquent. The Eloquent driver is often the decision-relevant one because it lets you read straight from a legacy database during a parallel run instead of exporting to CSV first. Each importer maps one source onto one collection destination with per-field transforms.
- Can I preview a Statamic import before committing the rows?
- Yes. The Control Panel workflow includes a dry-run preview so you can validate rows before writing entries. Treat row counts as a smoke test rather than verification, and add relation-level assertions for any fields that reference other entries. Run a small batch first when testing a new mapping.
- How do I run a Statamic Importer import from the Artisan CLI?
- Imports can be run from the command line as well as the Control Panel, which makes them suitable for repeatable migrations and scheduled content syncs. Check the installed version's artisan list output for the exact command name before scripting it. Run command names have changed across 2.x minors, so do not trust published examples over the installed package.
- How do I create a custom Statamic importer or transform field values?
- Importer definitions are PHP classes that live in your application repo and are registered through the published config. Each definition maps a source onto a collection destination and can apply per-field transforms. Trust the installed abstract Importer class for method names, and use custom transforms for fieldtypes like Bard, Replicator, and Assets that need structured JSON payloads rather than raw HTML strings.
- Does statamic/importer support multisite and localized content?
- Yes, the addon works with multisite and localized content. Before launch, decide whether the first import is single-site or multisite and, if multisite, identify a per-site unique key. Also confirm whether a parallel run against a live legacy system is required, because that implies repeatable re-imports.
- Why are related entries empty after a Statamic Importer run?
- Silent partial success is the dominant failure mode: a run can report success at the row-count level while relationships are empty. Issue #148 covered related entries not resolving under the Eloquent driver, which is why 2.3.2 is the minimum version. Verify with relation-level assertions and confirm the external unique key is populated on every source row.
- Is Statamic Importer a two-way sync engine?
- No. Its scope is deliberately narrow: one-directional landing of external rows into entries. Requirements that look like CDC, two-way reconciliation, or cross-entry computed fields are out of remit and should be scoped as custom code rather than stretched configuration. Also watch for CSV type coercion, slug collisions, and stale search, Stache, or static caches after writes.
Weaver
How can I help you explore Laravel packages today?