Awesome
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:
#[ObservedBy([DeepSync::class])]
class User extends Model
{
use HasFactory;
use SoftDeletes;
protected $fillable = [
'name',
'is_active'
];
// Properties that trigger DeepSync
public $syncable = ['is_active'];
#[SyncTo]
public function posts(): HasMany
{
return $this->hasMany(Post::class, 'author_id');
}
}
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:
#[ObservedBy([DeepSync::class])]
class Post extends Model
{
use HasFactory;
use SoftDeletes;
protected $fillable = [
'title',
'body',
'author_id',
'is_active'
];
// Properties that trigger DeepSync
public $syncable = ['is_active'];
#[SyncFrom]
public function user(): BelongsTo
{
return $this->belongsTo(User::class, 'author_id');
}
}
Note that the
Post
model must contain the#[SyncFrom]
attribute, theis_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:
class Task {
return subtasks(): HasMany
return $this->hasMany(Subtask::class);
}
}
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:
#[ObservedBy([DeepSync::class])]
class Task extends Model
{
use HasFactory;
use SoftDeletes;
protected $fillable = [
'name',
'is_complete'
];
public $syncable = ['is_complete'];
#[SyncFrom]
public function subtasks(): HasMany
{
return $this->hasMany(Subtask::class);
}
}
Note that we are using the
#[SyncFrom]
attribute on the "parent" class here instead of#[SyncTo]
.
And in our Subtask
class:
#[ObservedBy([DeepSync::class])]
class Subtask extends Model
{
use HasFactory;
use SoftDeletes;
protected $fillable = [
'name',
'is_complete',
'task_id'
];
public $syncable = ['is_complete'];
#[SyncTo]
public function task(): BelongsTo
{
return $this->belongsTo(Task::class);
}
}
Now let's test it:
public function test_reverse_sync()
{
$task = Task::factory()->has(
Subtask::factory(3)->state(
function(array $attributes, Task $task) {
return [
'task_id' => $task->id
];
}
)
)->create();
$this->assertEquals(1, Task::count());
$this->assertEquals(3, Subtask::count());
$this->assertEquals(3, Task::find($task->id)->subtasks()->count());
// Task only becomes complete when all subtasks are complete
$subtask1 = Subtask::find(1);
$subtask1->update(['is_complete' => 1]);
$this->assertEquals(0, Task::find($task->id)->is_complete);
$subtask2 = Subtask::find(2);
$subtask2->update(['is_complete' => 1]);
$this->assertEquals(0, Task::find($task->id)->is_complete);
$subtask3 = Subtask::find(3);
$subtask3->update(['is_complete' => 1]);
$this->assertEquals(1, Task::find($task->id)->is_complete);
}
$ ~/laravel-deep-sync: vendor/bin/phpunit --testsuite=Feature --colors=always
PHPUnit 11.3.6 by Sebastian Bergmann and contributors.
Runtime: PHP 8.3.11
Configuration: /Users/christanner/Code/laravel-deep-sync/phpunit.xml
. 1 / 1 (100%)
Time: 00:00.238, Memory: 38.50 MB
OK (1 test, 6 assertions)
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