Support for Query Builder Pipelines in Laravel 12.4

The Laravel team released v12.4.0, which includes a query builder pipe() method, the ability to conditionally skip migrations, an Arr::sole() method, and more.

#Query Builder pipe() Method

Tim MacDonald contributed a pipe() method to the base query builder and Eloquent query builder. This method's functionality is the same as the Collection::pipe() method:

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

#Skipping Migrations

Dan Matthews conbributed the ability to programatically skip migrations by adding an optional shouldRun() method to a migration:

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

The shouldRun() method is considered for both migrate and rollback commands. See the Database Migrations documentation for details.

#Arr::sole() Method

Ralph J. Smit contributed a Arr::sole() method, similar to collections and Eloquent collections. Sole supports passing a simple array that will return the first item only if it is the only item. Also, you can pass a callable as the second argument:

Arr::sole(['foo']); // "foo"
 
// @throws \Illuminate\Support\ItemNotFoundException
Arr::sole(['foo'], fn (string $value) => $value === 'baz');
 
// @throws \Illuminate\Support\MultipleItemsFoundException
Arr::sole(['baz', 'foo', 'baz'], fn (string $value) => $value === 'baz');

#Queue fake Helper for Listeners Pushed

Luke Kuzmish contributed a listenersPushed() method you can use to assert a queue listener was pushed during a test:

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

#Model except() Method

Vishal Chavda contributed a Model::except() method to retrieve model attributes excluding specific keys. This method is the inverse of the only() method:

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

#Assert Does Not Throw Method

Günther Debrauwer contributed a assertDoesntThrow() method to easily assert that a block of code doesn't throw an exception

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

This method is documented in the HTTP Tests documentation.

#Where Null and Where Not Null JSON Assertions

Faissal Wahabali contributed whereNull() and whereNotNull() methods to Assertablejson instances. Here's an example from the pull request of how this works:

// Usage:
fn (AssertableJson $json) => $json->whereNull('error')
 
 
// Example from the Framework tests:
$assert = AssertableJson::fromArray([
    'bar' => 'value',
]);
 
$this->expectException(AssertionFailedError::class);
$this->expectExceptionMessage('Property [bar] should be null.');
 
$assert->whereNull('bar');

Edit: 04/01/2025

I somehow missed the new AsHtmlString Eloquent cast in v12.4! I wrote a separate post about it:

As of v12.4, you can automatically cast Eloquent attributes to an HTML string using the AsHtmlString cast. The framework already has an HtmlString class available; this cast stitches it together with Eloquent attributes.

#Release notes

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

#v12.4.0

• [12.x] Reset PHP’s peak memory usage when resetting scope for queue worker by @TimWolla in https://github.com/laravel/framework/pull/55069
• [12.x] Add AsHtmlString cast by @ralphjsmit in https://github.com/laravel/framework/pull/55071
• [12.x] Add Arr::sole() method by @ralphjsmit in https://github.com/laravel/framework/pull/55070
• Improve warning message in ApiInstallCommand by @sajjadhossainshohag in https://github.com/laravel/framework/pull/55081
• [12.x] use already determined related property by @browner12 in https://github.com/laravel/framework/pull/55075
• [12.x] use "class-string" where appropriate in relations by @browner12 in https://github.com/laravel/framework/pull/55074
• [12.x] QueueFake::listenersPushed() by @cosmastech in https://github.com/laravel/framework/pull/55063
• [12.x] Added except() method to Model class for excluding attributes by @vishal2931 in https://github.com/laravel/framework/pull/55072
• [12.x] fix: add TPivotModel default and define pivot property in {Belongs,Morph}ToMany by @calebdw in https://github.com/laravel/framework/pull/55086
• [12.x] remove @return docblocks on constructors by @browner12 in https://github.com/laravel/framework/pull/55076
• [12.x] Add NamedScope attribute by @shaedrich in https://github.com/laravel/framework/pull/54450
• [12.x] Improve syntax highlighting for stub type files by @kayw-geek in https://github.com/laravel/framework/pull/55094
• [12.x] Prefer new Collection over Collection::make by @AhmedAlaa4611 in https://github.com/laravel/framework/pull/55091
• [12.x] Fix except() method to support casted values by @vishal2931 in https://github.com/laravel/framework/pull/55124
• [12.x] Add testcase for findSole method by @mrvipchien in https://github.com/laravel/framework/pull/55115
• [12.x] Types: PasswordBroker::reset by @liamduckett in https://github.com/laravel/framework/pull/55109
• [12.x] assertThrowsNothing by @gdebrauwer in https://github.com/laravel/framework/pull/55100
• [12.x] Fix type nullability on PasswordBroker.events property by @jnoordsij in https://github.com/laravel/framework/pull/55097
• [12.x] Fix return type annotation in decrementPendingJobs method by @shane-zeng in https://github.com/laravel/framework/pull/55133
• [12.x] Fix return type annotation in compile method by @shane-zeng in https://github.com/laravel/framework/pull/55132
• [12.x] feat: Add whereNull and whereNotNull to Assertablejson by @faissaloux in https://github.com/laravel/framework/pull/55131
• [12.x] fix: use contextual bindings in class dependency resolution by @calebdw in https://github.com/laravel/framework/pull/55090
• Better return types for Illuminate\Queue\Jobs\Job::getJobId() and Illuminate\Queue\Jobs\DatabaseJob::getJobId() methods by @petrknap in https://github.com/laravel/framework/pull/55138
• Remove remaining @return tags from constructors by @mohammadrasoulasghari in https://github.com/laravel/framework/pull/55136
• [12.x] Various URL generation bugfixes by @stancl in https://github.com/laravel/framework/pull/54811
• Add an optional shouldRun method to migrations. by @danmatthews in https://github.com/laravel/framework/pull/55011
• [12.x] Uri prevent empty query string by @rojtjo in https://github.com/laravel/framework/pull/55146
• [12.x] Only call the ob_flush function if there is active buffer in eventStream by @tonysm in https://github.com/laravel/framework/pull/55141
• [12.x] Add CacheFlushed Event by @tech-wolf-tw in https://github.com/laravel/framework/pull/55142
• [12.x] Update DateFactory method annotations for Carbon v3 compatibility by @kayw-geek in https://github.com/laravel/framework/pull/55151
• [12.x] Improve docblocks for file related methods of InteractsWithInput by @SanderMuller in https://github.com/laravel/framework/pull/55156
• [12.x] Enhance FileViewFinder doc-blocks by @imanghafoori1 in https://github.com/laravel/framework/pull/55183
• Support using null-safe operator with null value by @willrowe in https://github.com/laravel/framework/pull/55175
• [12.x] Fix: Make Paginated Queries Consistent Across Pages by @tomchkk in https://github.com/laravel/framework/pull/55176
• [12.x] Add pipe method query builders by @timacdonald in https://github.com/laravel/framework/pull/55171
• [12.x] fix: one of many subquery constraints by @calebdw in https://github.com/laravel/framework/pull/55168
• [12.x] fix(postgres): missing parentheses in whereDate/whereTime for json columns by @saibotk in https://github.com/laravel/framework/pull/55159
• Fix factory creation through attributes by @davidstoker in https://github.com/laravel/framework/pull/55190
• [12.x] Fix Concurrency::run to preserve callback result order by @chaker2710 in https://github.com/laravel/framework/pull/55161
• [12.x] Log: Add optional keys parameter to Log::withoutContext to remove selected context from future logs by @mattroylloyd in https://github.com/laravel/framework/pull/55181
• [12.x] Add Expression type to param $value of QueryBuilder having() method by @faissaloux in https://github.com/laravel/framework/pull/55200
• [12.x] Add flag to disable where clauses for withAttributes method on Eloquent Builder by @AndrewMast in https://github.com/laravel/framework/pull/55199