Add freshOr and freshOrFail methods to Eloquent models

[faytec-tanbo]

Eloquent's fresh() method returns a new model instance or null when the model no longer exists:

$article = $article->fresh();

if ($article === null) {
    throw (new ModelNotFoundException())
        ->setModel(Article::class, $article_id);
}

This requires repeating the same null handling whenever a caller requires the model to still exist.

Eloquent query builders already provide methods such as firstOr, firstOrFail, findOr, and findOrFail. It would be useful for fresh() to provide the same alternatives:

$article->freshOr($callback);
$article->freshOrFail();

Broadcasting example

Broadcast events are one place where this is useful.

Without #[WithoutRelations], the same event may receive models with different relationships already loaded at different dispatch sites:

ArticleUpdated::dispatch(
    $article->load('author'),
);

ArticleUpdated::dispatch(
    $article->load('comments'),
);

If the event returns the model directly from broadcastWith():

public function broadcastWith(): array
{
    return [
        'article' => $this->article->toArray(),
    ];
}

Laravel serializes the loaded relationships with the queued event. The same event can therefore include author when dispatched from one place and comments when dispatched from another.

Adding #[WithoutRelations] prevents relationships loaded before dispatch from being serialized. However, this does not cover relationships loaded while the broadcast event is being handled because Laravel invokes broadcastOn() before broadcastWith().

For example, broadcastOn() can load a relationship that later affects the payload returned by broadcastWith():

#[WithoutRelations]
class ArticleUpdated implements ShouldBroadcast
{
    use SerializesModels;

    public function __construct(
        private readonly Article $article,
    ) {}

    public function broadcastOn(): array
    {
        $author = $this->article->load('author')->author;

        return [new PrivateChannel("users.{$author->id}")];
    }

    public function broadcastWith(): array
    {
        return [
            'article' => $this->article->toArray(),
        ];
    }
}

Because broadcastOn() loaded author, the payload now unexpectedly contains the relationship:

{
    "article": {
        "id": 1,
        "title": "Laravel Broadcasting",
        "author": {
            "id": 10,
            "name": "Taylor"
        }
    }
}

The event can retrieve a clean model in broadcastWith(), but it must repeat the null check:

public function broadcastWith(): array
{
    $article = $this->article->fresh();

    if ($article === null) {
        throw (new ModelNotFoundException())
            ->setModel(Article::class, $this->article->getKey());
    }

    return [
        'article' => $article->toArray(),
    ];
}

With freshOrFail(), this becomes:

public function broadcastWith(): array
{
    return [
        'article' => $this->article->freshOrFail()->toArray(),
    ];
}

Proposed API

/**
 * Reload a fresh model instance or execute the given callback.
 *
 * @template TValue
 *
 * @param  \Closure(): TValue  $callback
 * @param  array|string  $with
 * @return static|TValue
 */
public function freshOr(Closure $callback, $with = [])
{
    $with = is_string($with)
        ? array_slice(func_get_args(), 1)
        : $with;

    return $this->fresh($with) ?? $callback();
}

/**
 * Reload a fresh model instance or throw a model not found exception.
 *
 * @param  array|string  $with
 * @return static
 *
 * @throws \Illuminate\Database\Eloquent\ModelNotFoundException<static>
 */
public function freshOrFail($with = [])
{
    $model = $this->fresh(
        is_string($with) ? func_get_args() : $with
    );

    if (is_null($model)) {
        throw (new ModelNotFoundException())
            ->setModel(static::class, $this->getKey());
    }

    return $model;
}

The relationship arguments support the same array and variadic forms as fresh():

$article->freshOr(fn () => $fallback);
$article->freshOr(fn () => $fallback, ['author', 'comments']);
$article->freshOr(fn () => $fallback, 'author', 'comments');

$article->freshOrFail();
$article->freshOrFail(['author', 'comments']);
$article->freshOrFail('author', 'comments');

Benefits

• Removes repeated fresh() null checks.
• Provides symmetry with firstOr, firstOrFail, findOr, and findOrFail.
• Preserves the current fresh() relationship-loading syntax.
• Uses the existing ModelNotFoundException with the model class and key.
• Keeps fresh() unchanged and fully backwards compatible.
• Gives queued jobs and broadcast events a concise way to start from a clean model whose relationships do not depend on the dispatch site.
• Makes broadcast payloads deterministic when the same event is dispatched with different relationships already loaded.
• Prevents accidentally exposing unrelated relationship data through model serialization.
• Allows each job or event to explicitly declare the relationships it needs:

$article = $this->article->freshOrFail('author', 'comments');

This keeps the model-loading requirements local to the code that produces the payload instead of relying on the state of the model passed by its caller.

Related references

#9835

[Labeeb2339]

A small application-level helper can cover this today while the framework API is discussed:

trait RefreshesModels
{
    public function freshOrFail(array|string $with = []): static
    {
        $fresh = $this->fresh($with);

        if ($fresh === null) {
            throw (new ModelNotFoundException)->setModel(static::class, $this->getKey());
        }

        return $fresh;
    }
}

The important detail for the proposed framework method is to return the new instance from fresh() rather than refreshing $this in place. That keeps the loaded relationships on the event/job's original model from leaking into a payload, which is especially relevant when broadcastOn() loads a relation before broadcastWith() runs.

If this becomes a core API, the tests should cover: a deleted model throwing with the concrete model class/key, the array and variadic relationship forms, and a successful call returning a distinct fresh instance with only the requested relations. The existing fresh() contract and the query-builder firstOr/firstOrFail behavior are useful compatibility references: https://laravel.com/docs/12.x/eloquent#retrieving-models

[faytec-tanbo]

I’m currently using a Trait to implement this functionality, and it already meets my needs. The main reason I started this discussion was to see whether others have the same need, and whether this could potentially be integrated into the framework to benefit more people.

In fact, this isn’t limited to the broadcasting use case.

Whenever we need a clean model instance, there are situations where this method can be useful. In the past, when using fresh(), PHPStan would always complain about the possibility of null. With this method, I can get a clean model instance much more conveniently.

For example, consider a model injected through route model binding. When passing the model to a service for processing, the service may need to access one of the model’s relationships as part of its business logic. This can cause the relationship to be loaded unintentionally. Then, when the controller returns the response, that unexpectedly loaded relationship may also be included.

There are many similar situations where being able to get a clean model instance would be useful.

[shaedrich]

This could be simplified to

trait RefreshesModels
{
    public function freshOrFail(array|string $with = []): static
    {
        return throw_unless(
            $this->fresh($with),
            (new ModelNotFoundException)->setModel(static::class, $this->getKey()),
        );
    }
}

or

trait RefreshesModels
{
    public function freshOrFail(array|string $with = []): static
    {
        return throw_unless(
            $this->fresh($with),
            fn () => (new ModelNotFoundException)->setModel(static::class, $this->getKey()),
        );
    }
}