Handle enum instance when throwing errors involving query parameters

[jtheuerkauf]

Laravel Version

11.45+

PHP Version

8.3.22+

Database Driver & Version

No response

Description

Using an enum as an "ID" when using find() and its derivatives is supported because the where logic converts the instance via enum_value().

In Builder::findOrFail() the $id variable is passed to ModelNotFoundException::setModel() where it becomes part of the exception message. But nothing makes sure the value of the ID can be used in a string.

In 11.x up to 12.18 the line looks like:

if (is_null($result)) {
    throw (new ModelNotFoundException)->setModel(
        get_class($this->model), $id
    );
}

In setModel() method:

if (count($this->ids) > 0) {
    $this->message .= ' '.implode(', ', $this->ids);
}

I notice the same behavior would occur if the count of fetched Models doesn't match the ID count.

Steps To Reproduce

1. create table foo(id int) (no data)
2. artisan make:model Foo
3. Make new class enum FooNum: int { case One = 1; }
4. Query Foo::findOrFail(FooNum::One)

Expected error (approximately):
No query results for model [Foo] 1

Got instead (approximately):
PHP Fatal error: Uncaught Error: Object of class FooNum could not be converted to string

[achrafAa]

I believe the current behavior in findOrFail() reveals an architectural consideration worth discussing:

Layer Responsibility
The query builder's where() clause correctly handles Enum conversion because it's specifically processing query values. However, ModelNotFoundException shouldn't need to understand Enum formatting - its job is to display the received ID.

Parameter Validation
PHP type safety suggests the caller should provide properly formatted IDs (int/string). Most DBAL methods expect scalar values, and we wouldn't expect other object types to auto-convert.

Consistency Consideration
If we auto-convert Enums here, should we do the same for:

Other magic methods (__get(), __call())?

All exception messages?

Every parameter that might accept an ID?

Suggested Solutions:

A) Strict Approach (Recommended)
Document that Enum values must be explicitly converted:

Model::findOrFail(MyEnum::Case->value);

B) Conversion in Builder
If auto-conversion is desired, it should happen in Builder::find() before the query executes, not in the exception:

public function find($id, $columns = ['*'])
{
    $id = $id instanceof BackedEnum ? $id->value : $id;
    // ... existing logic
}

Question for Maintainers
Should Laravel:

Be strict about scalar IDs (requiring ->value), or Extend Enum auto-conversion to all ID parameters?

The first approach maintains cleaner separation of concerns, while the second prioritizes developer convenience. I'm happy to submit a PR for either direction once we agree on the philosophy.

[jtheuerkauf]

Other magic methods

1. Personally, I'd limit the amount of magic, as it can easily spiral out of control.
2. __call() definitely no. As noted, values are intended to be scalar going in. Allowing magic calls should be a non-starter.
3. What magic __get() pseudo-properties would be expected? Always a ->value dependency? Enforcement of that already seems shaky, and would add a lot of type-sniffing overhead.
4. __toString() This one I can get behind. It can still get out of control, but the return is predictable, and it's a one-step conversion with (string).

All exception messages?
I think anywhere that parameters are key information in the error, conversion should be supported. But I'm definitely not married to that opinion. Maintainers can make a better judgment call.

Every parameter that might accept an ID?
Again, judgment call for those in charge. My initial take is no, just IDs.

As for which approach to take...

A) Strict Approach

I see the benefits of this as far as predictable data and less type juggling under the hood, but doesn't that strictness lean against the Laravel philosophy? 😆

B) Conversion

Enums are already supported in a lot of the Builder code, so deprecating and retracting them doesn't seem beneficial. They can only represent a string or integer, and don't support magic methods (yet?) to incur other sorcery. To me they're safe enough to convert with locked-in predictable behavior.

One note on the suggested change:

public function find($id, $columns = ['*'])
{
    $id = enum_value($id);
    // ... existing logic
}

This would be more consistent with the rest of enum support, allowing for a UnitEnum to be converted to its ->name.

[crynobone]

Hey there, thanks for reporting this issue.

We'll need more info and/or code to debug this further. Can you please create a repository with the command below, commit the code that reproduces the issue as one separate commit on the main/master branch and share the repository here?

Please make sure that you have the latest version of the Laravel installer in order to run this command. Please also make sure you have both Git & the GitHub CLI tool properly set up.

laravel new bug-report --github="--public"

Do not amend and create a separate commit with your custom changes. After you've posted the repository, we'll try to reproduce the issue.

Thanks!

[jtheuerkauf]

https://github.com/jtheuerkauf/laravel-bug-55977

Just run the migration and seeder for the users table, then open a tinker prompt:

$ php artisan tinker
Psy Shell v0.12.8 (PHP 8.3.21 — cli) by Justin Hileman

> \App\Models\User::findOrFail(\App\Models\UserEnum::One)->pluck('id', 'name')->toJson();
= "{"Test User":1}"

> \App\Models\User::findOrFail(\App\Models\UserEnum::Ten)->pluck('id', 'name')->toJson();
   Error  Object of class App\Models\UserEnum could not be converted to string.

UserEnum::One will match the Test User, while UserEnum::Ten will find nothing, but fail to convert the enum to a string for the not-found error.

[crynobone]

Do you know which commit/PR implements enum support for Illuminate\Database\Eloquent\Builder::findOrFail()?

[jtheuerkauf]

Do you know which commit/PR implements enum support for Illuminate\Database\Eloquent\Builder::findOrFail()?

@crynobone If this was for me, I didn't add anything to change current behavior. The code is provided to reproduce the problem. I didn't feel it's my place to implement a fix until/unless maintainers decide on the appropriate solution.