Use sole() instead of first() in Route Model Binding

[hosni]

Currently, route model binding resolves models using first() after building the binding query.

For example, resolveRouteBinding() ultimately resolves the model like this:

framework/src/Illuminate/Database/Eloquent/Model.php

Lines 2460 to 2463 in b623055

	public function resolveRouteBinding($value, $field = null)
	{
	return $this->resolveRouteBindingQuery($this, $value, $field)->first();
	}

The same behavior exists for the other route binding methods (including soft-deletable bindings):

framework/src/Illuminate/Database/Eloquent/Model.php

Lines 2472 to 2475 in b623055

	public function resolveSoftDeletableRouteBinding($value, $field = null)
	{
	return $this->resolveRouteBindingQuery($this, $value, $field)->withTrashed()->first();
	}

Or:

framework/src/Illuminate/Database/Eloquent/Model.php

Lines 2485 to 2488 in b623055

	public function resolveChildRouteBinding($childType, $value, $field)
	{
	return $this->resolveChildRouteBindingQuery($childType, $value, $field)->first();
	}

Using first() means that if the route binding query unexpectedly matches multiple records, Laravel silently returns the first result. While this is the correct behavior for backward compatibility, some applications expect a stronger invariant: a route parameter should resolve to exactly one model.

Motivation

Some applications rely on route model binding to uniquely identify a resource. If the underlying query becomes ambiguous because of a bug or inconsistent data, silently returning the first record can hide the problem.

Examples:

Multi-tenant applications

Imagine a model that resolves by slug together with a tenant scope.

The expected query is effectively:

where tenant_id = ? and slug = ?

If a bug accidentally removes or bypasses the tenant scope, the query may become:

where slug = ?

If multiple tenants have the same slug, route model binding will silently return the first matching model.

Using sole() would immediately detect that the binding query is no longer unique.

Custom route binding queries

Applications can customize resolveRouteBindingQuery().

A mistake such as broadening the query (for example, using LIKE or unintentionally removing constraints) may cause multiple records to match.

Today, the first matching record is returned without any indication that the binding has become ambiguous.

Data inconsistencies

Even when uniqueness is expected, mistakes happen.

Examples include:

• duplicate UUIDs introduced during an import,
• duplicate slugs caused by legacy data,
• accidentally reusing values after schema changes,
• or any other data inconsistency that violates application assumptions.

sole() would fail fast instead of silently returning an arbitrary record.

Proposal

Allow models to opt into resolving route bindings using sole() instead of first().

This would be entirely opt-in and would not change the behavior of existing applications.

Possible API

Option 1: Interface

interface ResolvesRouteBindingsSolely
{
    //
}

Internally:

if ($this instanceof ResolvesRouteBindingsSolely) {
    return $query->sole();
}

return $query->first();

Option 2: Model method

protected function resolvesRouteBindingsUsingSole(): bool
{
    return true;
}

Then Laravel would internally choose between first() and sole() based on the method's return value.

Personally, I think the method-based approach fits Eloquent's existing customization style a little better, but either approach would work.

Concern

One question is how MultipleRecordsFoundException should be handled.

My expectation is that it should not be converted into a 404.

A route matching multiple models indicates that the application's uniqueness assumption has been violated, which seems more like a server-side error than a missing resource.

Question

Would you consider an opt-in mechanism like this to be a good addition to Laravel?

If so, I'm happy to implement it and open a pull request. I'm also happy to follow whichever API (interface, method, or another approach) you think fits the framework best.

[shaedrich]

• Option 3: Attribute
   No need for an empty interface, Laravel is embracing attributes already
• Option 4: Router flag method

Route::get('/{tenent}/projects/{slug}', [ProjectController::class, 'all'])->strictBinding();

[hosni]

Yeah, both options looks good! and I think we need both of them.