Cloner

Cloner is a trait for Laravel Eloquent models that lets you duplicate a model along with its relationships, including any attached files, and even copy the result to a completely different database connection. It fills a gap Eloquent leaves open: replicating a model’s related records is otherwise a manual, error-prone process.

You declare which relations are cloneable on the model, and Cloner walks hasMany, belongsToMany, and nested relations to recursively duplicate related rows, firing lifecycle events and callbacks along the way so you can customize behavior such as keeping unique columns unique or duplicating attached files on disk.

What You Get

• A Cloneable trait that adds duplicate() and duplicateTo($connection) methods to any Eloquent model
• Recursive cloning of declared $cloneable_relations, including nested relations on related models
• An AttachmentAdapter interface (with a built-in Bkwld\Upchuck adapter) for duplicating files referenced by cloned models
• onCloning()/onCloned() callbacks plus cloner::cloning/cloner::cloned Laravel events for custom logic during the clone lifecycle
• Configurable $clone_exempt_attributes to control which columns are excluded from the clone (id, timestamps, and any custom fields)

Common Use Cases

• Duplicating a CMS page or product along with its photos, translations, and other one-to-many relations
• Copying seed or template records between separate database connections (e.g., staging to production)
• Cloning a record for an A/B variant or draft while preserving unique constraints via onCloning() callbacks
• Replicating file-backed models (with images or documents) without deleting the originals’ shared files

Under The Hood

Architecture - The trait-based design centers on Cloneable (in src/Cloneable.php), which delegates the actual recursive-clone algorithm to a dedicated Cloner service class (src/Cloner.php) resolved from Laravel’s IoC container. Cloner walks the model’s $cloneable_relations, replicates the base attributes (excluding a merged list of exempt attributes), re-saves the clone, then recurses into each declared relation — reattaching hasMany/morphMany children to the new parent and re-creating pivot rows for belongsToMany without duplicating the related record itself. A pluggable AttachmentAdapter interface, bound in the IoC container as cloner.attachment-adapter, is invoked for any $cloneable_file_attributes so file duplication is decoupled from the storage implementation (the bundled adapter targets the bkwld/upchuck package).

Tech Stack - Pure PHP built against illuminate/support (Laravel 5.5 through 13.x), registered via a standard Laravel ServiceProvider. Tests run on PHPUnit across a wide compatible range (6.x-10.x) using illuminate/database, mockery, and league/flysystem-vfs to fake file storage, with Coveralls wired in for coverage reporting.

Code Quality - Three test files (ServiceProviderTest, FunctionalTest, CloneableTest) exercise the service provider registration, end-to-end cloning behavior, and the trait’s per-model API, giving reasonable coverage for a package of this size. The source favors small, single-purpose classes and PHP docblocks, though as an older Laravel package it doesn’t use PHP’s newer scalar/return type declarations throughout.

API Design - Adoption is a one-line use \Bkwld\Cloner\Cloneable; plus declaring $cloneable_relations on the model, and the API surface (duplicate(), duplicateTo(), onCloning()/onCloned()) maps closely to Eloquent’s own conventions, which keeps the learning curve low for existing Laravel developers. The README documents every option (exempt attributes, file attachments, events, multi-database cloning) with runnable code samples.