[11.x] Allow callback to be passed to updateOrInsert() to pass different $values if the record already exists

[Markshall]

Earlier today I found myself wanting to pass a different array of values to updateOrInsert() depending on whether the record already existed or not. Effectively, I only wanted to update a specific column on the initial insertion of a record, not any future updates of said record.

To do this, I defined an array with values I definitely want to update, then did a conditional check to see if the record exists to add more elements to the array, like so:

$values = [
  'name' => $data['name'],
  'email' => $data['email'],
];

$exists = DB::table('users')->where('user_id', $user_id)->exists();

if (! $exists) {
  $values['optional_column'] = $data['foobar'];
}

DB::table('users')->updateOrInsert(
  ['user_id' => $user_id],
  $values
);

updateOrInsert() already internally performs the check for existence, so the check was being executed twice.

This PR allows a callback to be passed that will return an array, instead of just passing an array with conditional keys (see example below).
An array is still able to be passed through, and is still set as the default parameter, for backwards compatibility.

DB::table('users')->updateOrInsert(
  ['user_id' => $user_id],
  function ($exists) use ($data) {
    if ($exists) {
      return [
        'name' => $data['name'],
        'email' => $data['email'],
      ];
    }

    return [
      'name' => $data['name'],
      'email' => $data['email'],
      'optional_column' => $data['foobar'],
    ];
  }
);

Of course, you could still do the conditional keys, but keep it contained within the callback for tidiness.

DB::table('users')->updateOrInsert(
  ['user_id' => $user_id],
  function ($exists) use ($data) {
    $values = [
      'name' => $data['name'],
      'email' => $data['email'],
    ];

    if (! $exists) {
      $values['optional_column'] = $data['foobar'];
    }

    return $values;
  }
);

[jeanmarinho529]

I think we can keep the parameter typing in this function.

[Markshall]

I think we can keep the parameter typing in this function.

Although the function itself will return an array, the argument being passed will still be a function so it will throw a TypeError based on that.

[rodrigopedra]

Use a union type, then?

public function updateOrInsert(array $attributes, callable|array $values = [])

[Markshall]

Use a union type, then?

public function updateOrInsert(array $attributes, callable|array $values = [])

Definitely. I'll amend my PR to update it.

I'm currently working in an old project running on PHP 7.4, so am unable to use union types. I just made the amends locally and then made the PR with what worked for me in that setup without accounting for the PHP 8 support in Laravel 11.