[11.x] Introduce firstOrFail for Database Query Builder

[alnahian2003]

Introduce firstOrFail for Database Query Builder:

This pull request introduces the firstOrFail method to the BuildsQueries class within Laravel's database query builder. This method mirrors the functionality of the existing firstOrFail method available in Eloquent models, providing a convenient way to retrieve the first result of a query or throw an exception if no record is found.

Benefits:

• Improved Code Readability: Using firstOrFail in your database queries can enhance code readability and maintain consistency with Eloquent usage.
• Reduced Boilerplate: This eliminates the need for explicit checks for null results followed by exception handling, streamlining your code.
• Error Handling Consistency: It enforces consistent error handling in both database queries and Eloquent models.

Implementation Details:

• The new firstOrFail method accepts two arguments:
  • $columns (optional): An array or string specifying the columns to select (defaults to '*').
  • $message (optional): A custom message to include in the thrown RecordNotFoundException.
• The method first calls first($columns) to retrieve the first result.
• If a result is found, it's returned directly.
• If no record is found, a RecordNotFoundException is thrown with the provided message (or a default message if none is given).

Testing:

• Two unit tests are included in DatabaseQueryBuilderTest:
  • testFirstOrFailMethodReturnsFirstResult verifies that the method correctly returns the first result when found.
  • testFirstOrFailMethodThrowsRecordNotFoundException ensures the method throws a RecordNotFoundException when no record exists.

Adoption:

Once merged, this method can be used directly in your database queries to retrieve the first result or gracefully handle situations where no record is found.

Example Usage:

$user = DB::table('flights')->firstOrFail();

// Or with where()
$user = DB::table('users')->where('id', 1)->firstOrFail();

// Or with a custom message
$post = DB::table('posts')->where('slug', 'my-post')->firstOrFail(message: 'No post found with that slug');

Thank You!

[saMahmoudzadeh]

improve code style: (using single quotation)

$this->expectExceptionMessage('No record found for the given query.');

[saMahmoudzadeh]

Hi @alnahian2003

Since you've added your pull request to version 11, it's better to also add [11.x] to the title.

[alnahian2003]

Hi @alnahian2003

Since you've added your pull request to version 11, it's better to also add [11.x] to the title.

Thanks for the suggestion!

[taylorotwell]

Thanks for your pull request to Laravel!

Unfortunately, I'm going to delay merging this code for now. To preserve our ability to adequately maintain the framework, we need to be very careful regarding the amount of code we include.

If possible, please consider releasing your code as a package so that the community can still take advantage of your contributions!

If you feel absolutely certain that this code corrects a bug in the framework, please "@" mention me in a follow-up comment with further explanation so that GitHub will send me a notification of your response.