[12.x] Add resource helper functions to Model/Collections #55107

TimKunze96 · 2025-03-20T18:59:17Z

This PR adds a couple of helper functions that will make generating resource instances a lot more fluent.

Currently we need to do this:

UserResource::make(User::find(1));

// or

UserResource::collection(User::query()->active()->paginate());

After change:

User::find(1)->toResource(UserResource::class);

User::query()->active()->paginate()->toResourceCollection(UserResource::class);

mohammadrasoulasghari · 2025-03-22T18:21:42Z

thanks for pr, but I don't think the difference between UserResource::make(User::find(1)) and User::find(1)->toResource(UserResource::class) is significant enough to justify this API change.

Also, no test has been written for them.

TimKunze96 · 2025-03-22T18:53:27Z

I agree that it is not a big difference at a first glance, but especially when queries become quite long it is a significant upgrade in terms of readability. At the moment we are forced to introduce an intermediate variable or nest long query builder calls. This can get messy real fast, especially when being used in conjunction with defered/optional props in Inertia.js that require a function.

// Messy nesting required for shorthand function

$modules = fn () => ModuleResource::collection(Module::query()
  ->withDefaultRelations()
  // potentially many more calls
  ->withCommonSearch($search)
  ->simplePaginate(40, page: $search->page));

// or forced to use normal function

$modules =  function () use ($search) {
  $models = Module::query()
  ->withDefaultRelations()
  // potentially many more calls
  ->withCommonSearch($search)
  ->simplePaginate(40, page: $search->page);

  return ModuleResource::collection($modules);
 }

// arguably easier to write and more readable

$modules =  fn () => Module::query()
  ->withDefaultRelations()
  ->withCommonSearch($search)
  // potentially many more calls
  ->simplePaginate(40, page: $search->page)
  ->toResourceCollection(ModuleResource::class);

I'm happy to write the necessary tests for it too if the discussion about adding this feature is still open.

Also this is a pure enhancement, the "old way" of creating resources would still be valid.

taylorotwell · 2025-03-23T00:39:40Z

@TimKunze96 I kinda dig this. I wonder if we could add some auto-discovery to it based on conventions. 👀

So that you could just do User::find(1)->toResource() or User::all()->toResourceCollection() if you want, while still allowing explicit arguments as well.

TimKunze96 · 2025-03-23T21:54:24Z

I added a basic implementation of this. I think there is technically an edge case bug in there: Since the Paginator Instance does not "remember" what model it got generated by (as far as I could tell) I have to infer the model type via the items, but if the item list is empty it would just run fine, even if the related resource does not exist.

So to make it absolutely bulletproof the paginator would need to remember the calling class.

mohammadrasoulasghari · 2025-03-24T00:28:42Z

src/Illuminate/Database/Eloquent/Collection.php

+
+        $model = $this->first();
+
+        assert(is_object($model), 'Resource collection guesser expects the collection to contain objects.');


Using assertions in production code is risky as they may be disabled in production environments (zend.assertions=-1). When assertions fail in this state, no proper errors are thrown, leading to silent failures or unexpected behavior. Better to use explicit exceptions with meaningful error messages for reliable error handling.

https://www.php.net/manual/en/ini.core.php#ini.zend.assertions

see : \Illuminate\Database\Eloquent\Collection::toQuery

TimKunze96 · 2025-03-24T11:05:41Z

I changed the code to explicitly throw a LogicException if the provided or auto-discovered resource does not exist. There are now tests that cover all possible cases for each model, collection, and paginator.

The tests currently use class aliases to simulate the existence of the corresponding resource classes, although there may be a better approach.

siarheipashkevich · 2025-03-26T08:27:53Z

src/Illuminate/Database/Eloquent/Model.php

+     *
+     * @return class-string<JsonResource>
+     */
+    protected function guessResourceName(): string


There is a lot of duplications, maybe we can avoid the duplications?

Yeah you are right. I refactored the code to use traits instead.

… collection

TimKunze96 · 2025-03-26T09:33:49Z

I refactored to code to make use of traits.

It also gets applied to the base collection class instead of the eloquent collection class, since there are many cases were users mutate query results and end up with regular collections instead of eloquent collections.

shaedrich · 2025-03-27T07:39:28Z

@TimKunze96 I kinda dig this. I wonder if we could add some auto-discovery to it based on conventions. 👀

So that you could just do User::find(1)->toResource() or User::all()->toResourceCollection() if you want, while still allowing explicit arguments as well.

For custom collections it might also be convenient to define the collections resource class on the collection class via $collectionClass or newCollection() as either

a class property (e.g. $resourceClass)
a getter method (e.g. newResource() or getResourceClass() or getResourceClassName())
an attribute (e.g. #[CollectionResource] or #[ResourceClass])

shaedrich · 2025-04-02T07:57:40Z

src/Illuminate/Http/Resources/TransformsToResource.php

-        throw_unless(class_exists($resourceClass), \LogicException::class, sprintf('Failed to find resource class for model [%s].', $className));
+        throw_unless(
+            class_exists($resourceClass = static::guessResourceName()),
+            LogicException::class, sprintf('Failed to find resource class for model [%s].', get_class($this))


I'd put each argument on a separate line for consistency

Suggested change

LogicException::class, sprintf('Failed to find resource class for model [%s].', get_class($this))

LogicException::class,

sprintf('Failed to find resource class for model [%s].', get_class($this))

shaedrich · 2025-04-02T08:00:30Z

src/Illuminate/Http/Resources/TransformsToResource.php

+        throw_unless(
+            class_exists($resourceClass = static::guessResourceName()),
+            LogicException::class, sprintf('Failed to find resource class for model [%s].', get_class($this))
+        );

        return $resourceClass::make($this);


This might be a decent use case for tap():

Suggested change

throw_unless(

class_exists($resourceClass = static::guessResourceName()),

LogicException::class, sprintf('Failed to find resource class for model [%s].', get_class($this))

);

return $resourceClass::make($this);

$resourceClass = tap(static::guessResourceName(), fn (string $resourceClass) => throw_unless(

class_exists($resourceClass),

LogicException::class, sprintf('Failed to find resource class for model [%s].', get_class($this))

));

return $resourceClass::make($this);

Would be nice if one could do something like this:

$resourceClass = throw_unless( static::guessResourceName(), class_exists(...), LogicException::class, sprintf('Failed to find resource class for model [%s].', get_class($this)) ); return $resourceClass::make($this);

Or if there was a global when() helper 🤔

$resourceClass = when( static::guessResourceName(), class_exists(...), fn () => throw new LogicException(sprintf('Failed to find resource class for model [%s].', get_class($this))), ); return $resourceClass::make($this);

Or a Stringable helper 🤔

Suggested change

throw_unless(

class_exists($resourceClass = static::guessResourceName()),

LogicException::class, sprintf('Failed to find resource class for model [%s].', get_class($this))

);

return $resourceClass::make($this);

$resourceClass = Str::of(static::guessResourceName())

->when(

class_exists(...),

fn () => throw new LogicException(sprintf('Failed to find resource class for model [%s].', get_class($this))),

)

->value();

return $resourceClass::make($this);

taylorotwell · 2025-04-02T20:01:13Z

Thanks!

rodrigopedra · 2025-04-05T14:58:16Z

@taylorotwell as outlined on issue #55272, this PR added a missing dependency to illuminate/http to the illuminate/database component.

As such, projects using only the illuminate/database component outside of Laravel are failing due to the missing dependency.

I am not sure if this could be considered a breaking change due to this.

Avoid regression issue introduced in #55107 fixes #55272 Signed-off-by: Mior Muhammad Zaki <[email protected]>

* [12.x] Fix `illuminate/database` usage as standalone package Avoid regression issue introduced in #55107 fixes #55272 Signed-off-by: Mior Muhammad Zaki <[email protected]> * Update composer.json * Update composer.json --------- Signed-off-by: Mior Muhammad Zaki <[email protected]> Co-authored-by: Taylor Otwell <[email protected]>

grantholle · 2025-04-08T20:13:41Z

I tried doing something very similar in 2020... #35515

TimKunze96 added 3 commits March 20, 2025 19:49

Add resource helper functions

0909ce1

Fix doc-block style

b7d0768

Remove empty line

469709a

TimKunze96 changed the title ~~Add resource helper functions to Model/Collections~~ [12.x] Add resource helper functions to Model/Collections Mar 20, 2025

Make resource param optional and guess resource name

a4f0faf

mohammadrasoulasghari reviewed Mar 24, 2025

View reviewed changes

TimKunze96 added 6 commits March 24, 2025 09:38

Use throw_unless instead of assert

491522e

Extract name guessing function

c060601

Add tests for resource helpers

7ef6563

Fix formatting

ada10bd

Fix namespace conflicts and add current page

48c0865

Use more descriptive LogicException instead of Exception

93f3df6

siarheipashkevich reviewed Mar 26, 2025

View reviewed changes

Refactor to use traits and extend base collection instead of eloquent…

5f7092d

… collection

Ensure trait method exists

fbf4f78

taylorotwell added 3 commits April 1, 2025 14:37

formatting

6e878f4

formatting

28c1d3f

formatting

c738f7f

shaedrich reviewed Apr 2, 2025

View reviewed changes

taylorotwell added 3 commits April 2, 2025 14:49

adjust tests and logic

9e9f8a6

add testS

bf7676b

remove comment

bbe8ffb

taylorotwell merged commit cc889e6 into laravel:12.x Apr 2, 2025
38 of 39 checks passed

rodrigopedra mentioned this pull request Apr 5, 2025

Class Illuminate\Database\Eloquent\Model use a missing dependency #55272

Closed

crynobone added a commit that referenced this pull request Apr 7, 2025

[12.x] Fix illuminate/database usage as standalone package

98042f6

Avoid regression issue introduced in #55107 fixes #55272 Signed-off-by: Mior Muhammad Zaki <[email protected]>

crynobone mentioned this pull request Apr 7, 2025

[12.x] Fix illuminate/database usage as standalone package #55309

Merged

crynobone added a commit that referenced this pull request Apr 7, 2025

[12.x] Fix illuminate/database usage as standalone package

a0e1502

Avoid regression issue introduced in #55107 fixes #55272 Signed-off-by: Mior Muhammad Zaki <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[12.x] Add resource helper functions to Model/Collections #55107

[12.x] Add resource helper functions to Model/Collections #55107

TimKunze96 commented Mar 20, 2025 •

edited

Loading

mohammadrasoulasghari commented Mar 22, 2025

TimKunze96 commented Mar 22, 2025 •

edited

Loading

taylorotwell commented Mar 23, 2025 •

edited

Loading

TimKunze96 commented Mar 23, 2025

mohammadrasoulasghari Mar 24, 2025 •

edited

Loading

TimKunze96 commented Mar 24, 2025

siarheipashkevich Mar 26, 2025

TimKunze96 Mar 26, 2025

TimKunze96 commented Mar 26, 2025 •

edited

Loading

shaedrich commented Mar 27, 2025 •

edited

Loading

shaedrich Apr 2, 2025

shaedrich Apr 2, 2025

shaedrich Apr 2, 2025

shaedrich Apr 2, 2025

shaedrich Apr 2, 2025 •

edited

Loading

taylorotwell commented Apr 2, 2025

rodrigopedra commented Apr 5, 2025

grantholle commented Apr 8, 2025


		$model = $this->first();

		assert(is_object($model), 'Resource collection guesser expects the collection to contain objects.');

	LogicException::class, sprintf('Failed to find resource class for model [%s].', get_class($this))
	LogicException::class,
	sprintf('Failed to find resource class for model [%s].', get_class($this))

[12.x] Add resource helper functions to Model/Collections #55107

[12.x] Add resource helper functions to Model/Collections #55107

Conversation

TimKunze96 commented Mar 20, 2025 • edited Loading

mohammadrasoulasghari commented Mar 22, 2025

TimKunze96 commented Mar 22, 2025 • edited Loading

taylorotwell commented Mar 23, 2025 • edited Loading

TimKunze96 commented Mar 23, 2025

mohammadrasoulasghari Mar 24, 2025 • edited Loading

Choose a reason for hiding this comment

TimKunze96 commented Mar 24, 2025

siarheipashkevich Mar 26, 2025

Choose a reason for hiding this comment

TimKunze96 Mar 26, 2025

Choose a reason for hiding this comment

TimKunze96 commented Mar 26, 2025 • edited Loading

shaedrich commented Mar 27, 2025 • edited Loading

shaedrich Apr 2, 2025

Choose a reason for hiding this comment

shaedrich Apr 2, 2025

Choose a reason for hiding this comment

shaedrich Apr 2, 2025

Choose a reason for hiding this comment

shaedrich Apr 2, 2025

Choose a reason for hiding this comment

shaedrich Apr 2, 2025 • edited Loading

Choose a reason for hiding this comment

taylorotwell commented Apr 2, 2025

rodrigopedra commented Apr 5, 2025

grantholle commented Apr 8, 2025

TimKunze96 commented Mar 20, 2025 •

edited

Loading

TimKunze96 commented Mar 22, 2025 •

edited

Loading

taylorotwell commented Mar 23, 2025 •

edited

Loading

mohammadrasoulasghari Mar 24, 2025 •

edited

Loading

TimKunze96 commented Mar 26, 2025 •

edited

Loading

shaedrich commented Mar 27, 2025 •

edited

Loading

shaedrich Apr 2, 2025 •

edited

Loading