Deep Replicate

Laravel's Model::replicate() makes one unsaved copy of one model. Deep Replicate copies a relationship graph that you choose into new, persisted records, in a single transaction. For each relation path you decide whether its records are copied, reused, or skipped.

#Installation

Install the package with Composer. Laravel discovers the service provider and the DeepReplicate facade automatically.

#Requirements

• PHP 8.1, 8.2 or 8.3
• Laravel 10.0 or newer within 10.x (illuminate/database, illuminate/support, illuminate/container, illuminate/contracts)

Each Laravel major has its own release line with the same API. Pick the line that matches your application (see Compatibility).

#Composer Installation

composer require pharaonic/laravel-deep-replicate

There is no configuration file to publish and no migration to run.

#Add the trait (optional)

The trait adds deepReplicate() to a model. The facade and the DeepReplicator service work on any model without it.

1use Illuminate\Database\Eloquent\Model;
2use Pharaonic\Laravel\DeepReplicate\Concerns\DeepReplicates;
3 
4class Order extends Model
5{
6    use DeepReplicates;
7}

#Basic Usage

#Why native replicate() is not enough

$order->replicate() returns one unsaved Order with the same attributes. It copies no related records, and it may carry the source's loaded relations into the clone. Deep Replicate builds on that primitive. It replicates every selected model, links the copies to each other, and saves the whole graph in one transaction.

#Three equivalent entry points

The model trait, the facade, and the injected service all return the same ReplicationBuilder. Nothing is read or written until you call replicate() or dryRun().

 1use Pharaonic\Laravel\DeepReplicate\DeepReplicator;
 2use Pharaonic\Laravel\DeepReplicate\Facades\DeepReplicate;
 3 
 4// Model trait: the first argument is required.
 5$result = $order->deepReplicate('items')->replicate();
 6 
 7// Facade
 8$result = DeepReplicate::for($order)->copy('items')->replicate();
 9 
10// Dependency injection
11public function duplicate(Order $order, DeepReplicator $replicator)
12{
13    return $replicator->for($order, ['items'])->replicate()->model();
14}

#A selection is always required

There is no root-only deep replication. Use Laravel's replicate() for that.

1$order->deepReplicate();                            // ArgumentCountError
2$order->deepReplicate([]);                          // EmptyRelationshipSelectionException
3DeepReplicate::for($order)->replicate();            // EmptyRelationshipSelectionException
4DeepReplicate::for($order)->skip('payments')->replicate(); // EmptyRelationshipSelectionException

At least one path must be selected as copy or reuse. Preloading relations never selects them.

#Selecting paths

Positional paths are copied. An associative array assigns copy, reuse or skip; strategy names are case-insensitive. Nested paths are flat dot paths.

 1$order->deepReplicate('items');
 2$order->deepReplicate('items', 'customer');
 3$order->deepReplicate(['items', 'customer']);
 4$order->deepReplicate(['items' => 'copy', 'customer' => 'reuse', 'payments' => 'skip']);
 5 
 6DeepReplicate::for($order, [
 7    'items' => 'copy',
 8    'items.options' => 'copy',
 9    'items.product' => 'reuse',
10    'customer' => 'reuse',
11    'payments' => 'skip',
12])->replicate();

The fluent methods do the same and can be mixed with the array forms:

1$result = $order->deepReplicate('items', 'items.options')
2    ->reuse('items.product', 'customer')
3    ->skip('payments')
4    ->replicate();
5 
6$newOrder = $result->model();   // persisted root
7$map = $result->map();          // original => copy
8$stats = $result->stats();      // counts

1$result = DeepReplicate::for($order)
2    ->copy('items', 'items.options')
3    ->reuse('items.product', 'customer')
4    ->skip('payments')
5    ->replicate();
6 
7$newOrder = $result->model();   // persisted root
8$map = $result->map();          // original => copy
9$stats = $result->stats();      // counts

Every example in these docs works with both APIs. The trait's arguments are the facade's first copy() (or relations() array) call:

#Relationships

#Support matrix

Rejected combinations throw UnsupportedReuseException or UnsupportedRelationshipException before anything is written.

#Foreign keys you did not select

A copy keeps every raw attribute of its source except the primary key and the managed timestamps. Foreign keys of unselected or skipped relations keep their original values.

1$new = $post->deepReplicate('comments')->replicate()->model();
2 
3$new->author_id === $post->author_id; // true, although "author" was not selected

1$new = DeepReplicate::for($post)->copy('comments')->replicate()->model();
2 
3$new->author_id === $post->author_id; // true, although "author" was not selected

#Copy and reuse of a parent

1$order->deepReplicate('customer')->replicate();                // new customer, new customer_id
2$order->deepReplicate(['customer' => 'reuse'])->replicate();  // same customer_id

1DeepReplicate::for($order)->copy('customer')->replicate();  // new customer, new customer_id
2DeepReplicate::for($order)->reuse('customer')->replicate(); // same customer_id

A selected BelongsTo or MorphTo with a null key stays null and adds no record. When the key is set but the query does not return the record (it is missing, filtered, or hidden by a scope), the key is kept and the dry run reports a missing_target warning.

#Polymorphic relations

MorphOne and MorphMany copies receive the new parent's id and its morph class, which is the morph map alias when one is registered. MorphTo resolves each record's class from its stored type through Relation::morphMap(), and keeps the stored type exactly as it is. A nested path through MorphTo must exist on every class it reaches:

1// Activities of posts and videos: Video has no "comments" relation.
2$activity->deepReplicate('subject', 'subject.comments')->replicate();
3// InvalidRelationshipPathException: ... [subject.comments] ... Video

1// Activities of posts and videos: Video has no "comments" relation.
2DeepReplicate::for($activity)->copy('subject', 'subject.comments')->replicate();
3// InvalidRelationshipPathException: ... [subject.comments] ... Video

#What counts as a relation

A path segment must be a public, non-static method without required parameters, declared by your model, that returns an Eloquent relation. Framework and package methods such as delete, save, replicate, restore or deepReplicate are never called, and a method whose declared return type cannot be a relation is rejected without being called.

#Nested Graphs

#Paths and precedence

A nested path implies copy of its unselected parents: copy('items.options') also copies items. A skipped nested path implies nothing.

The whole selection is normalized and validated before any query runs.

#One copy per original record

Every original record gets at most one copy per operation. A record reached through two copy paths is copied once and linked from both.

1// "items" and "activeItems" both reach the active item: it is copied once.
2$order->deepReplicate('items', 'activeItems')->replicate();

1// "items" and "activeItems" both reach the active item: it is copied once.
2DeepReplicate::for($order)->copy('items', 'activeItems')->replicate();

Identity is the resolved connection, the model class, and the primary key with its type. Integer 1 and string "1" are different records.

A record that one path copies and another reuses throws ConflictingIdentityStrategyException. A record copied through two paths whose rules configure it differently throws ConflictingNodeConfigurationException. A rule set on only one of the paths applies to the shared copy.

#Cycles

A selected path that leads back to the root resolves to the new root, so no second root is created:

1$result = $post->deepReplicate('author', 'author.posts')
2    ->configure('author', fn ($rule) => $rule->with(['email' => '[email protected]']))
3    ->replicate();
4 
5// The new author owns the new post and copies of the author's other posts.

1$result = DeepReplicate::for($post)
2    ->copy('author', 'author.posts')
3    ->configure('author', fn ($rule) => $rule->with(['email' => '[email protected]']))
4    ->replicate();
5 
6// The new author owns the new post and copies of the author's other posts.

#Insert order and foreign key cycles

Copies are inserted after the copies their foreign keys point to: a copied BelongsTo parent goes first, and a copied child goes after its parent. When the selection forms a foreign key cycle (a user's current_team_id points to a team whose owner_id points back to the user), the cycle is broken at its earliest-reached model. That model is inserted with the cycle column set to NULL, and the column is updated once its target exists.

When the database rejects that NULL value, the replication fails with UnresolvableForeignKeyCycleException and nothing is kept. Foreign key checks are never disabled.

#Pivots

BelongsToMany, MorphToMany and MorphedByMany paths recreate one new pivot row per source pivot row. A copy path points the row to the related record's copy, and a reuse path points it to the original record.

#What is copied

• Every column of the pivot table, including columns not declared with withPivot(). Values are copied raw, so casts are not applied twice.
• Each source row separately: two rows for the same related record become two new rows. Rows are never collapsed with sync().
• Not the surrogate key (id, or the custom pivot model's key), which the database or the pivot model generates again.
• New timestamps when the relation uses withTimestamps(). With preserveTimestamps(), the source pivot timestamps are kept.

Pivot constraints declared on the relation, such as wherePivot(), decide which rows are copied.

1// The new post is linked to the same tags; original tags and pivot rows are untouched.
2$post->deepReplicate(['tags' => 'reuse'])->replicate();

1// The new post is linked to the same tags; original tags and pivot rows are untouched.
2DeepReplicate::for($post)->reuse('tags')->replicate();

#Transforming pivot rows

transformPivot() receives the non-linking attributes, the source pivot model and the context, and returns the attributes to insert. copyPivot() only states the default, so you never need it.

1$item->deepReplicate(['tags' => 'reuse'])
2    ->copyPivot('tags')
3    ->transformPivot('tags', function (array $attributes, $sourcePivot, ReplicationContext $context): array {
4        $attributes['primary'] = false;
5 
6        return $attributes;
7    })
8    ->replicate();

1DeepReplicate::for($item)
2    ->reuse('tags')
3    ->copyPivot('tags')
4    ->transformPivot('tags', function (array $attributes, $sourcePivot, ReplicationContext $context): array {
5        $attributes['primary'] = false;
6 
7        return $attributes;
8    })
9    ->replicate();

Setting a parent key, related key, morph type or surrogate key throws ProtectedRelationshipAttributeException.

#Custom pivot models

A relation that uses ->using(CustomPivot::class) saves each new row through that pivot model, the way attach() does. Its casts and its model events run. Plain pivot tables are written with batched multi-row inserts, which fire no model events, as in Laravel itself. RelationRule::withoutEvents() on the pivot path silences custom pivot events.

#Constraints and limits

A unique pivot column that would be duplicated fails the insert and rolls back the whole replication. Change it with transformPivot(). maxPivotRows() (default 50,000) is checked while planning, before the first write.

#Attributes

#Root and path configuration

The builder's exclude(), with(), generate() and transform() configure the root copy only. configure() gives a RelationRule for one copied path, with the same methods plus withoutEvents() and preserveTimestamps().

 1use Pharaonic\Laravel\DeepReplicate\RelationRule;
 2use Pharaonic\Laravel\DeepReplicate\ReplicationContext;
 3 
 4$order->deepReplicate('items')
 5    ->exclude(['external_ref'])
 6    ->with(['status' => 'draft'])
 7    ->generate('slug', fn (Order $source, ReplicationContext $context) => 'order-copy-'.bin2hex(random_bytes(6)))
 8    ->transform(function (array $attributes, Order $source, ReplicationContext $context): array {
 9        $attributes['number'] .= '-COPY';
10 
11        return $attributes;
12    })
13    ->configure('items', function (RelationRule $rule): void {
14        $rule->exclude(['external_id'])->with(['state' => 'pending']);
15    })
16    ->replicate();

 1use Pharaonic\Laravel\DeepReplicate\Facades\DeepReplicate;
 2use Pharaonic\Laravel\DeepReplicate\RelationRule;
 3use Pharaonic\Laravel\DeepReplicate\ReplicationContext;
 4 
 5DeepReplicate::for($order)
 6    ->copy('items')
 7    ->exclude(['external_ref'])
 8    ->with(['status' => 'draft'])
 9    ->generate('slug', fn (Order $source, ReplicationContext $context) => 'order-copy-'.bin2hex(random_bytes(6)))
10    ->transform(function (array $attributes, Order $source, ReplicationContext $context): array {
11        $attributes['number'] .= '-COPY';
12 
13        return $attributes;
14    })
15    ->configure('items', function (RelationRule $rule): void {
16        $rule->exclude(['external_id'])->with(['state' => 'pending']);
17    })
18    ->replicate();

#Order of operations

For every copy:

1. Laravel's replicate() runs on the source (its replicating event fires). The primary key, the timestamps and the unique id columns are dropped. The source's loaded relations are removed from the copy.
2. exclude removes attributes.
3. with sets attributes through setAttribute(), so mutators and casts apply.
4. generate callbacks run once per copied record, in registration order.
5. transform callbacks receive and return the raw (stored) attributes, in registration order.
6. The engine sets the linking keys of the selected relations.
7. beforeModel callbacks run, then the copy is saved.

Raw values are copied as stored. JSON columns are not re-encoded, and a value encrypted by a mutator keeps its ciphertext, so it still decrypts to the same plaintext. $fillable, $guarded and $hidden never drop an attribute, because nothing is mass assigned.

#Protected attributes

The primary key and every linking key managed by a selected relation are protected: a BelongsTo foreign key, a MorphTo id and type, and the foreign key of a copied child. Changing one through exclude, with, generate, transform or beforeModel throws ProtectedRelationshipAttributeException. Foreign keys of unselected relations are yours to change:

1$order->deepReplicate('items')->with(['assigned_customer_id' => $bob->id])->replicate();

1DeepReplicate::for($order)->copy('items')->with(['assigned_customer_id' => $bob->id])->replicate();

#Unique values

Nothing is suffixed automatically. A unique slug, SKU or email copied as is fails the insert and rolls back the replication. Give it a value explicitly:

1$order->deepReplicate('items')
2    ->generate('slug', fn () => Str::slug($order->number.'-'.Str::random(6)))
3    ->configure('items', fn (RelationRule $rule) => $rule->generate('sku', fn (OrderItem $item) => $item->sku.'-2'))
4    ->replicate();

1DeepReplicate::for($order)
2    ->copy('items')
3    ->generate('slug', fn () => Str::slug($order->number.'-'.Str::random(6)))
4    ->configure('items', fn (RelationRule $rule) => $rule->generate('sku', fn (OrderItem $item) => $item->sku.'-2'))
5    ->replicate();

#Primary keys, UUIDs and ULIDs

Incrementing keys come from the database. A non-incrementing key is generated by the model's native unique id API: uniqueIds() and newUniqueId(), as Laravel's HasUuids and HasUlids define them from 9.30. Without it, register a generator for the key, or the copy throws MissingPrimaryKeyGeneratorException:

1$document->deepReplicate('pages')
2    ->generate('uuid', fn () => (string) Str::uuid())
3    ->configure('pages', fn (RelationRule $rule) => $rule->generate('uuid', fn () => (string) Str::uuid()))
4    ->replicate();

1DeepReplicate::for($document)
2    ->copy('pages')
3    ->generate('uuid', fn () => (string) Str::uuid())
4    ->configure('pages', fn (RelationRule $rule) => $rule->generate('uuid', fn () => (string) Str::uuid()))
5    ->replicate();

Other columns listed in uniqueIds() get new values too.

#Timestamps and soft deletes

Copies get new created_at and updated_at values, custom column names included. preserveTimestamps() keeps the source values on every copy and pivot row, and RelationRule::preserveTimestamps(false) opts one path out. A soft-deleted source is restored on its copy; preserveSoftDelete() keeps its deleted_at.

#Model defaults

A model using the trait may return fallback settings from deepReplicationDefaults(). They apply only to paths the caller selects, and they can never select a path or change a strategy.

1protected function deepReplicationDefaults(): array
2{
3    return [
4        'with' => ['status' => 'draft'],
5        'paths' => [
6            'items' => ['exclude' => ['external_id']],
7        ],
8    ];
9}

The keys are exclude, with, generate, transform, without_events and preserve_timestamps, at the root and under paths. Builder settings win: with and generate merge per attribute, and the other keys are replaced when the builder sets them.

#Loaded and Fresh Relations

#Fresh queries by default

Selected relations are queried again, following their definition: its constraints, the global scopes, and the foreign key and morph constraints. A relation already loaded on the source is ignored, so a constrained eager load never shrinks the copy by accident.

1$post->load(['comments' => fn ($q) => $q->where('approved', true)]);
2 
3$post->deepReplicate('comments')->replicate();                          // every comment
4$post->deepReplicate('comments')->usingLoaded('comments')->replicate(); // the approved ones

1$post->load(['comments' => fn ($q) => $q->where('approved', true)]);
2 
3DeepReplicate::for($post)->copy('comments')->replicate();                          // every comment
4DeepReplicate::for($post)->copy('comments')->usingLoaded('comments')->replicate(); // the approved ones

#usingLoaded()

usingLoaded($path) uses exactly the loaded collection or model on every source parent of that path, and throws MissingLoadedRelationException when one is missing. It never loads anything. It does not apply to descendant paths: list each one, and load it on every parent.

1$order->load('items.options');
2 
3$order->deepReplicate('items.options')->usingLoaded('items', 'items.options')->replicate();

1$order->load('items.options');
2 
3DeepReplicate::for($order)->copy('items.options')->usingLoaded('items', 'items.options')->replicate();

A loaded pivot carries only the columns that were loaded. The dry run warns (unloaded_pivot_columns) when the table has more; load them with withPivot().

#filter()

filter($path, $callback) constrains the query of one selected path. The callback receives the relation, as an eager-load constraint does. Several filters on a path all apply. The source model and its relations are never modified.

1$order->deepReplicate('items.options')
2    ->filter('items', fn ($query) => $query->where('active', true))
3    ->replicate();

1DeepReplicate::for($order)
2    ->copy('items.options')
3    ->filter('items', fn ($query) => $query->where('active', true))
4    ->replicate();

filter() and usingLoaded() on the same path throw IncompatibleRelationOptionsException. A filter on a BelongsTo or MorphTo path that excludes the parent keeps the original foreign key.

#Global scopes and soft deletes

Global scopes apply to every relation query. Soft-deleted children are therefore not copied unless you call withoutGlobalScopes(), which removes every global scope from the relation queries:

1$order->deepReplicate('items')->withoutGlobalScopes()->preserveSoftDelete()->replicate();

1DeepReplicate::for($order)->copy('items')->withoutGlobalScopes()->preserveSoftDelete()->replicate();

#Lifecycle

#Eloquent events

Events stay on by default. Every copy fires replicating, saving, creating, created and saved, and records read for the plan fire retrieved.

1$order->deepReplicate('items')->withoutEvents()->replicate(); // no model events at all
2 
3$order->deepReplicate('items.options')
4    ->configure('items', fn (RelationRule $rule) => $rule->withoutEvents()) // items only
5    ->replicate();

1DeepReplicate::for($order)->copy('items')->withoutEvents()->replicate(); // no model events at all
2 
3DeepReplicate::for($order)
4    ->copy('items.options')
5    ->configure('items', fn (RelationRule $rule) => $rule->withoutEvents()) // items only
6    ->replicate();

withoutEvents() uses Laravel's own Model::withoutEvents() for the duration of the operation. Listener registration keeps working, and the original dispatcher is always restored. A path's withoutEvents() wraps only the replication and the insert of that path's copies (and of its custom pivots), never the root or other paths.

#Callbacks

A beforeModel callback may change the copy, but not its primary key, its linking keys or its connection.

1$order->deepReplicate('items')
2    ->afterModel(function (Model $original, Model $copy, ReplicationContext $context): void {
3        // $copy->exists === true, links resolved
4    })
5    ->afterCommit(function (ReplicationResult $result): void {
6        dispatch(new NotifyOrderCopied($result->model()->getKey()));
7    })
8    ->replicate();

1DeepReplicate::for($order)
2    ->copy('items')
3    ->afterModel(function (Model $original, Model $copy, ReplicationContext $context): void {
4        // $copy->exists === true, links resolved
5    })
6    ->afterCommit(function (ReplicationResult $result): void {
7        dispatch(new NotifyOrderCopied($result->model()->getKey()));
8    })
9    ->replicate();

An exception in any callback before the commit rolls the whole replication back. An exception in afterCommit is thrown to you, but the data is already committed and stays.

#afterCommit and your own transactions

When the replication opens the outermost transaction, afterCommit runs right after it commits. Inside a transaction you opened, the callbacks wait for your outermost commit and are dropped if you roll back. That needs Connection::afterCommit(), which Laravel ships from 8.x. On Laravel 6 and 7, registering afterCommit inside your transaction throws AfterCommitUnavailableException before anything is written. The callback never runs early.

#The context

ReplicationContext gives root() (the original root), replica() (the new root, null before it is inserted), path() (null for the root), depth() (0 for the root) and connectionName().

#Transactions and Safety

#One transaction

replicate() runs in one transaction on the source model's connection. It plans the graph again inside that transaction, so a dry run's snapshot is never reused. Then it inserts, links, attaches pivots, runs the callbacks and commits. Any exception rolls back every row the operation wrote and is rethrown, with database errors kept as the original QueryException. Inside your own transaction the operation uses a savepoint, and your rollback also discards the replica.

The transaction is attempted once. A deadlock is not retried, because callbacks are not idempotent. Retry the whole call yourself if your application needs it.

#One connection

Every model of the graph must use the source's connection. A related model on another connection throws CrossConnectionReplicationException while planning, before any write. Connections are compared as resolved connection objects, so a model that names the default connection explicitly is not "another connection".

#Concurrency

The plan is read inside the transaction, so it reflects the transaction's isolation level, not a global snapshot. Under the default READ COMMITTED of MySQL or PostgreSQL, rows committed by others between two planning queries may be seen. Lock the source records (for example with lockForUpdate() in your own transaction) when concurrent writes must not change the graph.

#Security notes

• Relation paths are resolved through Eloquent metadata only; no SQL is built from path strings.
• Exception messages name classes, paths and columns, never attribute values.
• Global scopes and foreign key checks are never disabled implicitly.
• Files, media, cloud objects and external resources are not copied, even when an attribute holds their path. Copy them yourself in afterCommit.
• Builders are single-use objects with no shared state, so they are safe to create per request.

#Dry Run and Results

#dryRun()

dryRun() returns a ReplicationPlan. It runs the planning queries only: no INSERT, UPDATE or DELETE, no model events (retrieved included), and no lifecycle callbacks, transforms or generators. Filters do run, because they decide the graph.

1$plan = $order->deepReplicate('items', 'items.options')
2    ->reuse('items.product')
3    ->dryRun();
4 
5$plan->relationships();      // ['items' => 'copy', 'items.options' => 'copy', 'items.product' => 'reuse']
6$plan->stats();              // projected ReplicationStats
7$plan->estimatedModels();    // copies + reused records
8$plan->estimatedPivotRows();
9$plan->warnings();           // list of PlanningWarning (code(), path(), message())

 1$plan = DeepReplicate::for($order)
 2    ->copy('items', 'items.options')
 3    ->reuse('items.product')
 4    ->dryRun();
 5 
 6$plan->relationships();      // ['items' => 'copy', 'items.options' => 'copy', 'items.product' => 'reuse']
 7$plan->stats();              // projected ReplicationStats
 8$plan->estimatedModels();    // copies + reused records
 9$plan->estimatedPivotRows();
10$plan->warnings();           // list of PlanningWarning (code(), path(), message())

The counts are a snapshot. The data may change before replicate() runs. A builder can run dryRun() any number of times before replicate().

#ReplicationResult

1$result = $order->deepReplicate('items')->reuse('items.product')->replicate();
2 
3$result->model();                    // the new, persisted root (relations not loaded)
4$result->map()->get($originalItem);  // its copy, or null
5$result->map()->isReused($product);  // true
6$result->map()->all();               // identity key => copy
7$result->map()->reused();            // identity key => reused original
8$result->stats()->toArray();

1$result = DeepReplicate::for($order)->copy('items')->reuse('items.product')->replicate();
2 
3$result->model();                    // the new, persisted root (relations not loaded)
4$result->map()->get($originalItem);  // its copy, or null
5$result->map()->isReused($product);  // true
6$result->map()->all();               // identity key => copy
7$result->map()->reused();            // identity key => reused original
8$result->stats()->toArray();

Identity keys read {connection}|{class}|{key type}:{key}, for example mysql|App\Models\Item|integer:42. Reused originals are never listed as copies.

A builder is single-use. A second replicate(), or a dryRun() after replicate(), throws BuilderAlreadyExecutedException, even when the first call failed.

#Limits

A limit throws ReplicationLimitExceededException before the first write. Values below 1 throw InvalidArgumentException.

#Performance

Planning reads each selected relation with one query per chunk of parents (one per morph type for MorphTo), never one per parent. Each copy is one INSERT through Eloquent, so events and generated keys work. Plain pivot rows are inserted in batches. The identity map keeps every planned record in memory, so memory grows linearly with the graph (O(V + E)).

Measured on the package's test suite (an order with items, eight options per item and one reused tag per item; SQLite in memory, PHP 8.0, Laravel 6):

A network database adds one round trip per insert. Graphs much larger than these are better split into several operations.

#API Reference

#Entry points

#ReplicationBuilder

#RelationRule

#Exceptions

Every exception extends Exceptions\DeepReplicationException, which extends RuntimeException.

#Compatibility

Every Laravel major has its own release line with the same package API. Versions are N.minor.patch, where N is the Laravel major.

Further lines (11.x to 13.x) are opened one at a time, in order, each tested on every PHP version its Laravel major supports, up to PHP 8.5.

#Version-specific behavior

The databases tested are SQLite with foreign keys enforced and, in CI, MySQL and PostgreSQL.

#Examples

#1. Clone an order as a template

Copy the items and their options, keep the products and the customer, and start the copy as a draft.

 1use Pharaonic\Laravel\DeepReplicate\RelationRule;
 2 
 3public function store(Order $order)
 4{
 5    $copy = $order->deepReplicate('items', 'items.options')
 6        ->reuse('items.product', 'customer')
 7        ->skip('payments')
 8        ->with(['status' => 'draft'])
 9        ->generate('slug', fn () => 'order-'.Str::lower(Str::random(10)))
10        ->configure('items', fn (RelationRule $rule) => $rule->exclude(['external_id'])->with(['state' => 'pending']))
11        ->replicate()
12        ->model();
13 
14    return redirect()->route('orders.edit', $copy);
15}

 1use Pharaonic\Laravel\DeepReplicate\Facades\DeepReplicate;
 2use Pharaonic\Laravel\DeepReplicate\RelationRule;
 3 
 4public function store(Order $order)
 5{
 6    $copy = DeepReplicate::for($order)
 7        ->copy('items', 'items.options')
 8        ->reuse('items.product', 'customer')
 9        ->skip('payments')
10        ->with(['status' => 'draft'])
11        ->generate('slug', fn () => 'order-'.Str::lower(Str::random(10)))
12        ->configure('items', fn (RelationRule $rule) => $rule->exclude(['external_id'])->with(['state' => 'pending']))
13        ->replicate()
14        ->model();
15 
16    return redirect()->route('orders.edit', $copy);
17}

#2. Copy a catalog section with shared taxonomy

Products are copied with their variants; their tags stay shared, so only new pivot rows are written.

1$result = $category->deepReplicate('products', 'products.variants')
2    ->reuse('products.tags')
3    ->configure('products', fn (RelationRule $rule) => $rule->generate('sku', fn (Product $p) => $p->sku.'-'.$category->season))
4    ->replicate();
5 
6$result->stats()->pivotRowsCreated(); // one per original product-tag row

1$result = DeepReplicate::for($category)
2    ->copy('products', 'products.variants')
3    ->reuse('products.tags')
4    ->configure('products', fn (RelationRule $rule) => $rule->generate('sku', fn (Product $p) => $p->sku.'-'.$category->season))
5    ->replicate();
6 
7$result->stats()->pivotRowsCreated(); // one per original product-tag row

#3. Translate an article without duplicating its taxonomy

 1public function handle(Article $article, string $locale): Article
 2{
 3    return DeepReplicate::for($article)
 4        ->copy('sections', 'sections.blocks')
 5        ->reuse('categories', 'tags', 'author')
 6        ->with(['locale' => $locale, 'published_at' => null])
 7        ->generate('slug', fn (Article $source) => $source->slug.'-'.$locale)
 8        ->afterCommit(fn ($result) => TranslateArticle::dispatch($result->model()->getKey(), $locale))
 9        ->replicate()
10        ->model();
11}

1class Article extends Model
2{
3    use DeepReplicates;
4 
5    public function sections() { return $this->hasMany(Section::class); }
6    public function categories() { return $this->belongsToMany(Category::class); }
7    public function tags() { return $this->morphToMany(Tag::class, 'taggable'); }
8    public function author() { return $this->belongsTo(User::class); }
9}

#4. Check a large copy before running it

1$builder = fn () => DeepReplicate::for($project)->copy('tasks', 'tasks.checklist')->reuse('tasks.assignees');
2 
3$plan = $builder()->dryRun();
4 
5if ($plan->estimatedModels() > 5000) {
6    return back()->withErrors('This project is too large to duplicate at once.');
7}
8 
9$builder()->maxModels(5000)->replicate();

#5. Stay inside the tenant

Keep global scopes on (the default), and copy the relations whose keys must change instead of retaining them:

1// The copy keeps team_id: duplicating within the same team.
2$board->deepReplicate('columns', 'columns.cards')->replicate();
3 
4// Moving to another team: set the unmentioned key explicitly and check access first.
5Gate::authorize('create', [Board::class, $targetTeam]);
6$board->deepReplicate('columns', 'columns.cards')->with(['team_id' => $targetTeam->id])->replicate();

1// The copy keeps team_id: duplicating within the same team.
2DeepReplicate::for($board)->copy('columns', 'columns.cards')->replicate();
3 
4// Moving to another team: set the unmentioned key explicitly and check access first.
5Gate::authorize('create', [Board::class, $targetTeam]);
6DeepReplicate::for($board)->copy('columns', 'columns.cards')->with(['team_id' => $targetTeam->id])->replicate();

#Troubleshooting

#UNIQUE constraint failed on a slug, SKU or email

The value was copied as is, because nothing is suffixed automatically. Give it a value with generate(), with() or transform() on the root, or with configure() on the path. The failed replication left no rows behind.

#MissingPrimaryKeyGeneratorException

The model has a non-incrementing key and no native unique id generator. Register one with generate('<key>', ...) on that path, or use HasUuids or HasUlids on Laravel 9.30 or later.

#ProtectedRelationshipAttributeException

A callback, with, exclude or generate changed a primary key or a key managed by a selected relation. Change the relation's strategy instead, or leave the key to the engine.

#UnsupportedReuseException on a HasMany

Reusing children would move them away from their parent. Copy them, or skip them.

#The copy has fewer children than expected

A global scope (soft deletes, tenant scopes) or a relation constraint hid them, or a usingLoaded() relation was loaded with a constraint. Check dryRun()->estimatedModels(), and use withoutGlobalScopes() only when crossing scopes is intended.

#The copy still points to the original parent

That relation was not selected, or it was skipped or filtered out, so its foreign key was kept. Select it as copy, or set the key with with().

#AfterCommitUnavailableException

You registered afterCommit inside your own transaction on Laravel 6 or 7. Replicate outside the transaction, or dispatch the work yourself after your commit.

#UnresolvableForeignKeyCycleException

The selection forms a foreign key cycle and the column used to break it is NOT NULL. Make that column nullable, start from the other model, or do not select both directions.

#afterCommit never runs in my tests

RefreshDatabase wraps each test in a transaction that never commits. Use DatabaseMigrations or DatabaseTruncation for tests that depend on afterCommit.