Wp Import Laravel Package

Getting Started

This is a Statamic addon for pulling WordPress content (post types, taxonomies/terms, and their relationships) into Statamic collections and taxonomies. Treat it as an import tool, not a sync engine — most teams run it once per migration and then again in short bursts when content changes upstream.

1. Install into the Statamic app that will receive the content:

   composer require statamic-rad-pack/wp-import
   

2. Publish the config and read it top to bottom before running anything — it is where the WP endpoint, credentials, and the post-type/taxonomy → collection/taxonomy mappings live:

   php artisan vendor:publish --tag=wp-import-config
   

3. Confirm the exact command names shipped in your version rather than copying them from a blog post (they have moved around across minor releases):

   php please list | grep -i wp
   

4. First use case: pick one taxonomy (e.g. categories) and import only that, into a freshly created Statamic taxonomy with a blueprint whose field handles match what you intend to map. Verify term names, slugs, and parent/child nesting in the CP before importing a single post. Terms are the cheapest thing to get wrong and the most annoying thing to fix once posts reference them.

Look at first, in order: config/wp-import.php → the addon README's mapping examples → the importer classes under vendor/statamic-rad-pack/wp-import/src/ (they are readable and are the real documentation for edge cases).

Implementation Patterns

Dry run on a subset, then scale. Start with a single post type and a low per_page/limit, import into a throwaway collection, inspect the field data, then delete the collection and re-run properly. Content imports are hard to unwind once media and relationships are attached.

Import in dependency order. Taxonomies/terms → posts/pages → anything that resolves relationships. If you script the whole migration, wrap the individual commands in your own Artisan command so ordering and failure handling are explicit:

$this->call('wp-import:terms', ['--taxonomy' => 'category']);
$this->call('wp-import:posts', ['--type' => 'post']);

Keep a WP ID on every entry and term. Add an wp_id field to your blueprints (or rely on whatever identifier the addon persists) and index it. This is what makes re-imports idempotentish, lets you reconcile a partial run, and lets you write follow-up scripts that join Statamic entries back to their WordPress originals. Never key off the slug — WordPress slugs change and Statamic will happily create a duplicate.

Match blueprint handles to WP field names where you can. The mapping layer is thin; the less transformation you ask of it, the fewer surprises. Anything genuinely different (ACF repeaters, serialised meta, page builders) belongs in a post-import pass in your own code, not in the mapping config.

Run it in a queue-aware context for real sites. Big WordPress installs blow through PHP time limits. Either import per post type in separate invocations, or drive it from a job with a generous $timeout and chunking. Log the ID of the last successfully imported item so you can resume.

Version-pin in composer.json and re-run taxonomy imports after upgrades. This package has shipped several small taxonomy/term fixes in patch releases; the safe upgrade ritual is: upgrade → run the term import against a staging copy → diff the term counts and hierarchies → only then touch posts.

Gotchas and Tips

• v1.7.2 changes term/taxonomy import behaviour. After upgrading from 1.7.1, re-run your taxonomy import on staging and specifically check: duplicate terms created instead of matched, parent/child hierarchy preserved, slug collisions resolved the way you expect, and existing post↔term relationships still intact. Terms are matched by name/slug in ways that can silently create duplicates if your upstream data has near-identical names.
• Publishing the config is not optional-feeling but is. Many "the import did nothing" reports are an un-published or cached config. Run php please cache:clear after editing it; Statamic caches config aggressively in production.
• Auth and rate limits. WordPress's REST API needs application passwords or a similar auth mechanism, and shared hosts will rate-limit or 403 you partway through a large run. Symptoms look like truncated imports, not errors — always compare imported counts against wp_count_posts.
• per_page caps at 100 on WP. If you see exactly 100 (or a multiple) of something, you've hit pagination and the loop isn't continuing. Check the addon's pagination handling if the count looks suspiciously round.
• Media is a separate problem. Featured images and inline media references usually need a follow-up step (download, attach to an asset container, rewrite URLs in the HTML). Budget for it explicitly; don't assume the importer does it.
• Debug with verbosity and logs, not dd(). php please wp-import:... -v plus a look at storage/logs/laravel.log will show the HTTP failures the command swallows. If a run dies silently, drop a Log::debug() into the importer's request method in vendor/ temporarily.
• Extension points: the config mapping array is the primary customisation surface. Beyond that, importer classes are resolvable from the container — you can bind a subclass in a service provider to override transformation logic without forking. Check whether your version dispatches events per imported item; if it does, that's the cleanest place to attach your own post-processing (URL rewriting, SEO meta, redirects) rather than patching vendor code.
• Don't leave it installed forever. Once migration is done, remove the package and the WP credentials from .env. An import tool with write access to your content and a stored WordPress password is unnecessary surface area on a live site.