✨ Feat: Add firstOrInsert method to Query Builder with tests

[mohammadrasoulasghari]

This Pull Request introduces a new firstOrInsert method to the Laravel Query Builder.
The Laravel Query Builder currently lacks a firstOrInsert method, unlike Eloquent which offers both updateOrCreate and firstOrCreate. While updateOrInsert is available in the Query Builder, a dedicated firstOrInsert method was missing.
This omission has caused confusion and questions in forums, making the Query Builder less intuitive for common "find or create" scenarios. Developers often need a simple way to retrieve an existing record or create a new one if it doesn't exist, without the overhead of Eloquent models.

Implementation

The firstOrInsert method is implemented in the Illuminate\Database\Query\Builder class.

It works as follows:

1. Attempts to retrieve the first record matching the provided $attributes using where and first.
2. If a record is found, it is returned.
3. If no record is found, a new record is inserted using insert, combining the $attributes and $values.
4. The newly inserted record is then retrieved using where and first and returned.

Usage Example

DB::table('users')->firstOrInsert(
    ['email' => '[email protected]'],
    ['name' => 'Example User', 'password' => 'password']
);

This code will attempt to find a user with the email ‘[email protected]’.

Testing

This PR includes comprehensive unit tests to ensure the functionality and reliability of the firstOrInsert method. Tests cover scenarios for:

Retrieving existing records.
Inserting new records.
Using callable values for dynamic insertion.These tests provide confidence in the correctness of the implementation and will help prevent regressions in future changes.

[taylorotwell]

It's a bit more atomic to follow createOrFirst logic so there isn't a race condition.

[mohammadrasoulasghari]

It's a bit more atomic to follow createOrFirst logic so there isn't a race condition.

s there any built-in infrastructure in Query Builder for handling unique constraints, similar to Eloquent’s createOrFirst() method? Or do I need to implement this functionality myself for Query Builder? it’s already implemented in Eloquent but I couldn’t find a suitable equivalent in Query Builder?

@taylorotwell
@shaedrich