Statamic Replicator Transfer Laravel Package

Getting Started

This is the initial 1.0.0 release of justbetter/statamic-replicator-transfer, a Statamic addon for moving Replicator field data between entries, sites, or environments. The release notes only contain the initial addon commit, so treat the README and source as the primary documentation until the package matures.

Minimal setup:

composer require justbetter/statamic-replicator-transfer:^1.0
php artisan vendor:publish --tag=statamic-replicator-transfer-config
php artisan cache:clear
php artisan stache:clear

Statamic addons are typically auto-discovered through composer.json extra metadata. Confirm the service provider is registered:

php artisan about
php artisan list | grep -i replicator

Where to look first:

1. README.md for supported commands, routes, or public APIs.
2. The addon service provider and config file for bindings and extension points.
3. Any console commands under src/Console or src/Commands.
4. The package tests, if published, for expected input/output shapes.

First use case: copy a Replicator field from one entry to another in a local environment. Start with a simple field containing text and basic sets, verify the resulting YAML/JSON structure in the target entry, then expand to nested sets, assets, and relationships.

Because this is a 1.0.0 initial release, pin the version in composer.json and avoid assuming long-term API stability until a 1.1/2.0 release establishes conventions.

Implementation Patterns

One-off content transfers. Use the addon’s command or service to copy a Replicator field between entries. Keep source and target field handles aligned, or explicitly map handles if the package exposes a mapping option.

Content migration scripts. Wrap transfers in a Laravel command or seeder so they are repeatable:

use JustBetter\StatamicReplicatorTransfer\...;

public function handle()
{
    DB::transaction(function () {
        // transfer Replicator data from source entry to target entry
    });
}

This is useful when promoting approved content from staging to production or rebuilding entries after a schema change.

Environment promotion workflow. Author complex Replicator content in staging, export or transfer it, then import into production as part of a deployment step. Run the transfer after Statamic’s Stache has warmed and after asset containers and related entries exist.

Multisite duplication. Use the addon to copy Replicator sets between localized versions of an entry. Verify how the package handles site-specific asset containers and localized relationship targets.

Job-based bulk transfers. For many entries, dispatch queued jobs rather than transferring everything synchronously. Chunk by collection or entry ID to avoid long-running requests and partial writes.

Integration tips:

• Transfer into a draft or duplicate entry first, inspect the result, then publish.
• Keep a database snapshot before bulk operations.
• Use Statamic’s entry query builder to resolve source and target entries by ID, slug, or collection.
• If the package emits events, listen for them to log transfers or trigger follow-up indexing.
• Prefer the package’s public service/command over directly manipulating Replicator field values; direct array manipulation is brittle because Replicator stores nested set metadata and IDs.

Gotchas and Tips

• Sparse initial documentation. The 1.0.0 release notes do not describe configuration, commands, or API. Inspect the source and README before relying on assumed behavior.
• Pin the version. Initial addon releases often change method signatures and config keys. Use ^1.0 only if you are prepared for minor-version changes, or pin exactly during rollout.
• Replicator set IDs can collide. Replicator data includes internal set identifiers. Copying the same data into multiple entries may require regenerating IDs to avoid editor or preview issues. Check whether the package handles this automatically.
• Asset and relationship references are environment-specific. Asset container paths, asset IDs, and entry IDs differ between environments. Transfer only after assets and related entries exist in the target, or remap references explicitly.
• Clear Statamic’s Stache after transfers. Statamic caches content aggressively. Run php artisan stache:clear and php artisan cache:clear, then verify in the control panel.
• Test multisite behavior carefully. Localized entries can share or diverge Replicator data depending on field configuration. Confirm whether the addon writes to the origin site, a specific site, or all sites.
• Use a dry run or duplicate target. There may be no built-in rollback. Transfer into a copy first and inspect the raw field data in the entry’s Markdown/YAML file.
• Watch memory and timeout limits. Bulk Replicator transfers can be large. Use queues and chunking for anything beyond a handful of entries.
• Debug with verbose output and logs. Run commands with -v, check storage/logs/laravel.log, and inspect the target entry’s source file before and after transfer.
• Extension points are likely limited at 1.0.0. If the addon binds a service in its provider, prefer resolving that service over duplicating package logic. If behavior is missing, open an issue rather than forking early; the package is young and the API may still be forming.