Document returned array shape for sync methods (#52070)

Author: devfrey

src/Illuminate/Database/Eloquent/Relations/Concerns/InteractsWithPivotTable.php

@@ -67,7 +67,7 @@ public function toggle($ids, $touch = true)
      * Sync the intermediate tables with a list of IDs without detaching.
      *
      * @param  \Illuminate\Support\Collection|\Illuminate\Database\Eloquent\Model|array  $ids
-     * @return array
+     * @return array{attached: array, detached: array, updated: array}
      */
     public function syncWithoutDetaching($ids)
     {
@@ -79,7 +79,7 @@ public function syncWithoutDetaching($ids)
      *
      * @param  \Illuminate\Support\Collection|\Illuminate\Database\Eloquent\Model|array  $ids
      * @param  bool  $detaching
-     * @return array
+     * @return array{attached: array, detached: array, updated: array}
      */
     public function sync($ids, $detaching = true)
     {
@@ -133,7 +133,7 @@ public function sync($ids, $detaching = true)
      * @param  \Illuminate\Support\Collection|\Illuminate\Database\Eloquent\Model|array  $ids
      * @param  array  $values
      * @param  bool  $detaching
-     * @return array
+     * @return array{attached: array, detached: array, updated: array}
      */
     public function syncWithPivotValues($ids, array $values, bool $detaching = true)
     {

types/Database/Eloquent/Relations.php

@@ -71,6 +71,9 @@ function test(User $user, Post $post, Comment $comment, ChildUser $child): void
     assertType('Illuminate\Database\Eloquent\Collection<int, Illuminate\Types\Relations\Role>', $user->roles()->saveManyQuietly($roles));
     assertType('array<int, Illuminate\Types\Relations\Role>', $user->roles()->saveManyQuietly($roles->all()));
     assertType('array<int, Illuminate\Types\Relations\Role>', $user->roles()->createMany($roles));
+    assertType('array{attached: array, detached: array, updated: array}', $user->roles()->sync($roles));
+    assertType('array{attached: array, detached: array, updated: array}', $user->roles()->syncWithoutDetaching($roles));
+    assertType('array{attached: array, detached: array, updated: array}', $user->roles()->syncWithPivotValues($roles, []));
     assertType('Illuminate\Support\LazyCollection<int, Illuminate\Types\Relations\Role>', $user->roles()->lazy());
     assertType('Illuminate\Support\LazyCollection<int, Illuminate\Types\Relations\Role>', $user->roles()->lazyById());
     assertType('Illuminate\Support\LazyCollection<int, Illuminate\Types\Relations\Role>', $user->roles()->cursor());