Laravel 12.19 Adds a useEloquentBuilder Attribute, a FailOnException Queue Middleware, and More

The Laravel team released v12.19.0 with a UseEloquentBuilder PHP attribute, an AsFluent model cast, FailOnException job middleware, assert redirect back with errors, and more:

#Use Eloquent Builder PHP Attribute

Hristijan Manasijev contributed a UseEloquentBuilder PHP attribute to register a custom Eloquent query builder for a model. This feature has been proposed a few times and is now in Laravel 12 for those using custom query builders.

Before you might write something like this to use a custom query builder:

class MyModel extends Model
{
    // ...
    public function newEloquentBuilder($query)
    {
        return new CustomBuilder($query);
    }
}

Now you can use the framework-provided PHP attribute:

use Illuminate\Database\Eloquent\Attributes\UseEloquentBuilder;
 
#[UseEloquentBuilder(CustomBuilder::class)]
class MyModel extends Model
{
    // ...
}

See Pull Request #56025 for details.

#AsFluent Model Cast

Azim Kordpour contributed a AsFluent model cast

namespace App\Models;
 
use Illuminate\Database\Eloquent\Casts\AsFluent;
use Illuminate\Database\Eloquent\Model;
 
class Passenger extends Model
{
    protected function casts(): array
    {
        return [
            'address' => AsFluent::class,
        ];
    }
}

After defining a model cast as a fluent instance, you can use it with a model instance:

$passanger = Passenger::first();
 
// Get nested values
$passenger->address->get('office.street');
$passenger->address->get('home.street');
 
// Update it as a Fluent instance...
$passenger->address = new Fluent([
           'office' => ['street' => 'new street'],
           'office' => ['home' => 'new street']
]);
 
// Or as an array...
$passenger->address = [
    'office' => ['street' => 'new street'],
    'office' => ['home' => 'new street']
];

See the Eloquent: Mutators & Casting documentation for details on using model casts.

#Fail on Exception Job Middleware

Luke Kuzmish contributed a queue job middleware to fail the job on a particular exception—the default behavior is to retry based on how many retries are left. Using this middleware, you might know that a job never has a chance to run successfully and can instantly fail the job:

use Illuminate\Queue\Middleware\FailOnException;
 
/**
 * Get the middleware the job should pass through.
 */
public function middleware(): array
{
    return [
        new FailOnException([AuthorizationException::class])
    ];
}

The FailOnException accepts a callable instance if you want custom logic, which takes the thrown exception and the job instance:

new FailOnException(fn (\Throwable $e, mixed $job): bool => /* ... */);

See the Failing Jobs on Specific Exceptions section in the Queues documentation.

#Asserting Redirects with Errors

Ahmed Alaa contributed two test response methods to assert whether the response is redirecting back to the previous page and the session has given errors:

$response->assertRedirectBackWithErrors(
    array $keys = [], $format = null, $errorBag = 'default'
);

The second helper is the opposite, asserting a redirect back and verifying that no errors exist in the session:

$response->assertRedirectBackWithoutErrors();

These methods are now documented in the official 12.x documentation.

#Add a Mailable Attachment from an UploadedFile Instance

Rodrigo Pedra Brum contributed a fromUploadedFile() method to the mail Attachment class, which allows you to convert an UploadedFile instance into a mailable attachment.

use Illuminate\Mail\Attachment;
 
Attachment::fromUploadedFile($file);

See Pull Request #56027 for details.

#Release notes

You can see the complete list of new features and updates below and the diff between 12.18.0 and 12.19.0 on GitHub. The following release notes are directly from the changelog:

#v12.19.0

• [11.x] Fix validation to not throw incompatible validation exception by @crynobone in https://github.com/laravel/framework/pull/55963
• [12.x] Correct testEncryptAndDecrypt to properly test new methods by @KIKOmanasijev in https://github.com/laravel/framework/pull/55985
• [12.x] Check if file exists before trying to delete it by @Jellyfrog in https://github.com/laravel/framework/pull/55994
• Clear cast caches when discarding changes by @willtj in https://github.com/laravel/framework/pull/55992
• [12.x] Handle Null Check in Str::contains by @Jellyfrog in https://github.com/laravel/framework/pull/55991
• [12.x] Remove call to deprecated getDefaultDescription method by @jnoordsij in https://github.com/laravel/framework/pull/55990
• Bump brace-expansion from 2.0.1 to 2.0.2 in /src/Illuminate/Foundation/resources/exceptions/renderer by @dependabot in https://github.com/laravel/framework/pull/55999
• Enhance error handling in PendingRequest to convert TooManyRedirectsE… by @achrafAa in https://github.com/laravel/framework/pull/55998
• [12.x] fix: remove Model intersection from UserProvider contract by @calebdw in https://github.com/laravel/framework/pull/56013
• [12.x] Remove the only @return tag left on a constructor by @JordanchoEftimov in https://github.com/laravel/framework/pull/56001
• [12.x] Introduce ComputesOnceableHashInterface by @Jacobs63 in https://github.com/laravel/framework/pull/56009
• [12.x] Add assertRedirectBackWithErrors to TestResponse by @AhmedAlaa4611 in https://github.com/laravel/framework/pull/55987
• [12.x] collapseWithKeys - Prevent exception in base case by @DeanWunder in https://github.com/laravel/framework/pull/56002
• [12.x] Standardize size() behavior and add extended queue metrics support by @sylvesterdamgaard in https://github.com/laravel/framework/pull/56010
• [11.x] Fix symfony/console:7.4 compatibility by @crynobone in https://github.com/laravel/framework/pull/56015
• [12.x] Improve constructor PHPDoc for controller middleware definition by @JordanchoEftimov in https://github.com/laravel/framework/pull/56021
• Remove @return tags from constructors by @michaelnabil230 in https://github.com/laravel/framework/pull/56024
• [12.x] sort helper functions in alphabetic order by @gigabites19 in https://github.com/laravel/framework/pull/56031
• [12.x] add Attachment::fromUploadedFile method by @rodrigopedra in https://github.com/laravel/framework/pull/56027
• [12.x]: Add UseEloquentBuilder attribute to register custom Eloquent Builder by @KIKOmanasijev in https://github.com/laravel/framework/pull/56025
• [12.x] Improve PHPDoc for the Illuminate\Cache folder files by @JordanchoEftimov in https://github.com/laravel/framework/pull/56028
• [12.x] Add a new model cast named asFluent by @azim-kordpour in https://github.com/laravel/framework/pull/56046
• [12.x] Introduce FailOnException job middleware by @cosmastech in https://github.com/laravel/framework/pull/56037
• [12.x] isSoftDeletable(), isPrunable(), and isMassPrunable() to model class by @shaedrich in https://github.com/laravel/framework/pull/56060