Laravel 12.4 Update: New Features Include Query Builder Pipe(), Conditional Migrations, and More

Laravel's latest release, v12.4.0, introduces several valuable features aimed at improving query handling, migration management, and testing capabilities. Among the highlights are the Query Builder pipe() method, a mechanism for skipping migrations based on conditions, a new Arr::sole() function, and several other helpful improvements.

1. Query Builder pipe() Method

Contributor: Tim MacDonald

One of the standout additions is the pipe() method, now available in both the query builder and Eloquent. This new function operates similarly to the Collection::pipe() method, allowing developers to apply operations in a pipeline and streamline their queries.

Usage Example:

$records = DB::query()
    ->from('...')
    // other query modifications
    ->tap(new TappableScope)  // returns the query object
    ->pipe(new ActionScope);  // executes and returns the result
        

2. Conditional Migration Skipping

Laravel 12.4 introduces the ability to conditionally skip migrations. A new shouldRun() method has been added, enabling you to determine whether a migration should run based on custom conditions, such as whether a feature is active.

Usage Example:

return new class extends Migration
{
    public function shouldRun()
    {
        return Feature::active(Flights::class);
    }

    // other migration logic
}
        

3. Arr::sole() Method

A new Arr::sole() method joins the array helper family, mimicking the behavior of the Collection::sole() method. It ensures that you retrieve a single element from an array only if it is the sole item. It throws exceptions when there are multiple matches or no matches at all.

Usage Example:

Arr::sole(['foo']); // Returns "foo"

// Throws ItemNotFoundException if the item isn't found
Arr::sole(['foo'], fn (string $value) => $value === 'baz');

// Throws MultipleItemsFoundException for multiple matching items
Arr::sole(['baz', 'foo', 'baz'], fn (string $value) => $value === 'baz');
        

4. Queue Fake Helper for Listener Assertions

Laravel 12.4 now includes the listenersPushed() method for asserting that a queue listener was triggered during testing. This enhancement improves the testing experience by providing an easy way to check whether an event was handled.

Usage Example:

Queue::fake();
event(new SomeEvent(value: 'look, a value!'));

$this->assertCount(
    1,
    Queue::listenersPushed(
        SomeEventListener::class,
        fn (SomeEvent $event) => $event->value === 'look, a value!'
    )
);
        

5. Model except() Method

A new Model::except() method allows you to retrieve a model's attributes while excluding specific fields, serving as the reverse of the only() method.

Usage Example:

$user->except('id', 'email');
        

6. assertDoesntThrow() Method

This new method simplifies testing by asserting that a given block of code does not throw an exception.

Usage Example:

$this->assertDoesntThrow(fn () => (new ProcessOrder)->execute());
        

7. Where Null and Where Not Null JSON Assertions

Laravel now supports the whereNull() and whereNotNull() methods in AssertableJson instances, allowing for easy verification of null values in JSON responses.

Usage Example:

fn (AssertableJson $json) => $json->whereNull('error')

// Example from framework tests
$assert = AssertableJson::fromArray([
    'bar' => 'value',
]);

$this->expectException(AssertionFailedError::class);
$this->expectExceptionMessage('Property [bar] should be null.');

$assert->whereNull('bar');
        

With these updates, Laravel 12.4 continues to enhance the framework's flexibility, improve testing capabilities, and streamline database operations, making it an even more powerful tool for developers.