Laravel 10.20 Released

This week, the Laravel team released v10.20 with a createOrFirst() method, benchmark a single callable, a new response JSON assertion, and more:

Eloquent createOrFirst() method

Tony Messias contributed a createOrFirst() method which attempts to create a new record. If the unique constraint violation occurs, this method attempts to find the matching record:

$result = Model::createOrFirst(
    ['email' => 'user@example.com'], // Attributes to find
    ['name' => 'Example User'] // values merged with attributes if created
);

Use trashed relationship even without soft deletes

Mior Muhammad Zaki some updates that support using withTrashed(), withoutTrashed(), onlyTrashed() on a morph relationship:

This would be useful in some 3rd party packages as this has become an issue where it's not possible to define the relationship such as $this->morphTo()->withTrashed() unless all
relationship uses SoftDeletes trait...

You can learn more about this change in the description of Pull Request #47880.

Benchmark a single callable and get a result

Tim MacDonald contributed a value() method to the benchmark utility class, which you can use the measure a given callable inline and get the resulting value:

public function list()
{
    [$response, $duration] = Benchmark::value(
        fn () => Http::get('https://external-service.com/list.json')
    );
 
    if ($duration > 1000) {
      Log::warning('external-service.com is running slow');
    }
 
    return $response->json();
}

Allow default values when merging data into an API resource

Choraimy Kroonstuiver contributed the ability to pass a default value to mergeWhen() that will be used. This cleans up logic around mergeWhen() and mergeUnless when you want to provide defaults:

Here's an example from the pull request, showing how you'd do this before Laravel 10.20:

class MyResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            /* other properties */
            $this->mergeWhen($this->hasSpecificData(), $this->specificData()),
            $this->mergeUnless($this->hasSpecificData(), static::genericData()),
        ];
    }
}

And here's what you can do now:

class MyResource extends JsonResource
{
    public function toArray($request): array
    {
        return [
            /* other properties */
            $this->mergeWhen($this->hasSpecificData(), $this->specificData(), static::genericData()),
        ];
    }
}

Canonical JSON path assertion

Günther Debrauwer contributed a assertJsonPathCanonicalizing() method you can use to check if a JSON response contains all the expected values without a given order.

$users = User::factory()->count(2)->create();
 
$response = $this->get('/api/users');
$response->assertJsonPathCanonicalizing(
    'data.*.id',
    $users->pluck('id')->all()
);

See Pull Request #48117 for more details and example tests that demonstrate this in action.

Release notes

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

v10.20.0

• [10.x] Allow default values when merging values into a resource by @axlon in https://github.com/laravel/framework/pull/48073
• [10.x] Adds a createOrFirst method to Eloquent by @tonysm in https://github.com/laravel/framework/pull/47973
• [10.x] Allow utilising withTrashed(), withoutTrashed() and onlyTrashed() on MorphTo relationship even without SoftDeletes Model by @crynobone in https://github.com/laravel/framework/pull/47880
• [10.x] Mark Request JSON data to be InputBag in docblocks by @jnoordsij in https://github.com/laravel/framework/pull/48085
• [10.x] Markdown Mailables: Allow omitting Footer and Header when customising components by @jorisnoo in https://github.com/laravel/framework/pull/48080
• [10.x] Update EmailVerificationRequest return docblock by @ahmedash95 in https://github.com/laravel/framework/pull/48087
• [10.x] Add commonly reusable Composer related commands from 1st party packages by @crynobone in https://github.com/laravel/framework/pull/48096
• [10.x] Add ability to measure a single callable and get result by @timacdonald in https://github.com/laravel/framework/pull/48077
• [10.x] Fixes incorrect method visibility and add unit tests for Illuminate\Support\Composer by @crynobone in https://github.com/laravel/framework/pull/48104
• [10.x] Skip convert empty string to null test by @hungthai1401 in https://github.com/laravel/framework/pull/48105
• [10.x] Using complete insert for mysqldump when appending migration dump to schema file by @emulgeator in https://github.com/laravel/framework/pull/48126
• [10.x] Add hasPackage method to Composer class by @emargareten in https://github.com/laravel/framework/pull/48124
• [10.x] Add assertJsonPathCanonicalizing method by @gdebrauwer in https://github.com/laravel/framework/pull/48117
• [10.x] Configurable storage path via environment variable by @sl0wik in https://github.com/laravel/framework/pull/48115
• [10.x] Support providing subquery as value to where builder method by @gdebrauwer in https://github.com/laravel/framework/pull/48116
• [10.x] Minor Tweaks by @utsavsomaiya in https://github.com/laravel/framework/pull/48138