Download the PHP package c-tanner/laravel-deep-sync without Composer

Laravel Deep Sync

Elegantly sync properties across any relationship.

Installation

Requirements:

• PHP >= 8.2
• Laravel >= 10

composer require c-tanner/laravel-deep-sync

More than just cascading soft-deletes

Cascading soft-deletes within Laravel has been covered by a number of great packages in the past. At its core, though, deleted_at is just another class property.

While DeepSync does offer native support for cascading / syncing soft-deletes, you can also assign any model property as syncable - and choose which models should follow suit.

Let's take the classic User / Post example:

Here, our User model defines it's is_active property as syncable, and that the Post model should SyncTo changes.

Then, in our Post model:

Note that the Post model must contain the #[SyncFrom] attribute, the is_active class property, and the $syncable array.

Observer events

DeepSync currently supports saved() and deleted() model events. Note that in Laravel, update() also calls save() under the hood, and will also trigger the DeepSync observer.

Polymorphic support

Cascading properties in one-to-one or one-to-many relationships is straightforward: when the "parent" model changes state, DeepSync finds the "child" records using Eloquent relationship methods tagged with the #[SyncTo] attribute and updates the property to the same value. Child models are also inspected for their relationship methods, and the process continues down the tree.

For many-to-many or many-to-one relationships, DeepSync only updates child records if all parents share the same state.

In the example above, we can see that when User A is deleted, Post A is also deleted, as User A is it's only parent. Since Post B, even though it also related to User A, is also related to User B, and therefore remains unchanged.

DeepSync relationships cascade, and will traverse to as many levels as are defined:

Though these examples use delete actions for ease of demonstration, these concepts apply to all class properties defined in the syncable array.

Omnidirectional syncs

Because we can define the direction of SyncFrom and SyncTo independent of our actual class hierarchy, a pretty neat feature becomes available.

Let's say we have two models, Task and Subtask. The class hierarchy is as you would expect:

However, let's say that both classes have a property, is_complete, which defaults to false, and we want to automatically mark a Task complete only when all related Subtasks are also complete:

Let's look at how to acheive this in the code:

Note that we are using the #[SyncFrom] attribute on the "parent" class here instead of #[SyncTo].

And in our Subtask class:

Now let's test it:

Configuration

Ironically, Observers in Laravel aren't very observable (I think that's what irony is, right?). This can make debugging quite difficult, so DeepSync comes with verbose logging configured by default, output to your application's default log channel. You can turn logging off, or change the log severity by publishing the configuration file:

php artisan vendor:publish --tag=deepsync