Метод sync

Метод sync применяется к отношениям типа belongsToMany и позволяет синхронизировать связи в промежуточной таблице. Первым параметром передаётся массив идентификаторов связанных моделей, которые должны присутствовать в промежуточной таблице. Все связи, не перечисленные в массиве, будут удалены. Вторым параметром можно указать, следует ли отключать события моделей.

Метод возвращает массив с ключами 'attached', 'detached' и 'updated', содержащий идентификаторы связей, которые были добавлены, удалены или обновлены соответственно.

Синтаксис

<?php
	$model->relation()->sync($ids);
	$model->relation()->sync($ids, $detaching);
?>

Пример базового использования

Давайте синхронизируем роли пользователя, указав только нужные идентификаторы:

<?php
	use App\Models\User;
	use App\Models\Role;
	
	$user = User::find(1);
	$res = $user->roles()->sync([1, 3, 5]);
	
	var_dump($res);
?>

Результат выполнения кода:

[
	"attached" => [1, 3, 5],
	"detached" => [],
	"updated" => []
]

В этом примере все существующие связи пользователя будут удалены, а новые связи с ролями 1, 3 и 5 будут созданы.

Пример с массивом ключей

Давайте синхронизируем роли, передавая массив с дополнительными данными для промежуточной таблицы:

<?php
	use App\Models\User;
	use App\Models\Role;
	
	$user = User::find(2);
	$res = $user->roles()->sync([
		1 => ['expires_at' => '2025-12-31'],
		3 => ['expires_at' => '2025-12-31'],
		4 => ['expires_at' => '2025-12-31']
	]);
	
	var_dump($res);
?>

Результат выполнения кода:

[
	"attached" => [1, 3, 4],
	"detached" => [],
	"updated" => []
]

В этом примере создаются связи с дополнительными данными в колонке 'expires_at' промежуточной таблицы.

Пример с отключением детачмента

Давайте синхронизируем роли без удаления существующих связей, передав второй параметр false:

<?php
	use App\Models\User;
	use App\Models\Role;
	
	$user = User::find(3);
	$res = $user->roles()->sync([1, 2, 3], false);
	
	var_dump($res);
?>

Результат выполнения кода:

[
	"attached" => [],
	"detached" => [],
	"updated" => []
]

В этом примере существующие связи не удаляются, а только добавляются новые, если их ещё нет.

Пример с обновлением данных

Давайте синхронизируем роли, обновляя данные существующих связей:

<?php
	use App\Models\User;
	use App\Models\Role;
	
	$user = User::find(4);
	$res = $user->roles()->sync([
		1 => ['expires_at' => '2026-01-01'],
		2 => ['expires_at' => '2026-01-01']
	]);
	
	var_dump($res);
?>

Результат выполнения кода:

[
	"attached" => [],
	"detached" => [],
	"updated" => [1, 2]
]

В этом примере существующие связи с ролями 1 и 2 обновляются, устанавливая новое значение в колонке 'expires_at'.

Смотрите также

метод attach,
который добавляет новые связи без удаления существующих
метод detach,
который удаляет указанные связи из промежуточной таблицы
метод syncWithoutDetaching,
который синхронизирует связи без удаления существующих
метод toggle,
который переключает состояние связей (добавляет или удаляет)