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

* Add resource helper functions

* Fix doc-block style

* Remove empty line

* Make resource param optional and guess resource name

* Use throw_unless instead of assert

* Extract name guessing function

* Add tests for resource helpers

* Fix formatting

* Fix namespace conflicts and add current page

* Use more descriptive LogicException instead of Exception

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

* Ensure trait method exists

* formatting

* formatting

* formatting

* adjust tests and logic

* add testS

* remove comment

---------

Co-authored-by: Taylor Otwell <[email protected]>

Author: TimKunze96

src/Illuminate/Collections/Collection.php

@@ -5,6 +5,7 @@
 use ArrayAccess;
 use ArrayIterator;
 use Illuminate\Contracts\Support\CanBeEscapedWhenCastToString;
+use Illuminate\Http\Resources\TransformsToResourceCollection;
 use Illuminate\Support\Traits\EnumeratesValues;
 use Illuminate\Support\Traits\Macroable;
 use InvalidArgumentException;
@@ -24,7 +25,7 @@ class Collection implements ArrayAccess, CanBeEscapedWhenCastToString, Enumerabl
     /**
      * @use \Illuminate\Support\Traits\EnumeratesValues<TKey, TValue>
      */
-    use EnumeratesValues, Macroable;
+    use EnumeratesValues, Macroable, TransformsToResourceCollection;
 
     /**
      * The items contained in the collection.

src/Illuminate/Database/Eloquent/Model.php

@@ -17,6 +17,7 @@
 use Illuminate\Database\Eloquent\Relations\Concerns\AsPivot;
 use Illuminate\Database\Eloquent\Relations\HasManyThrough;
 use Illuminate\Database\Eloquent\Relations\Pivot;
+use Illuminate\Http\Resources\TransformsToResource;
 use Illuminate\Support\Arr;
 use Illuminate\Support\Collection as BaseCollection;
 use Illuminate\Support\Str;
@@ -39,7 +40,8 @@ abstract class Model implements Arrayable, ArrayAccess, CanBeEscapedWhenCastToSt
         Concerns\HidesAttributes,
         Concerns\GuardsAttributes,
         Concerns\PreventsCircularRecursion,
-        ForwardsCalls;
+        ForwardsCalls,
+        TransformsToResource;
     /** @use HasCollection<\Illuminate\Database\Eloquent\Collection<array-key, static & self>> */
     use HasCollection;
 

src/Illuminate/Http/Resources/TransformsToResource.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Illuminate\Http\Resources;
+
+use Illuminate\Http\Resources\Json\JsonResource;
+use Illuminate\Support\Str;
+use LogicException;
+
+trait TransformsToResource
+{
+    /**
+     * Create a new resource object for the given resource.
+     *
+     * @param  class-string<JsonResource>|null  $resourceClass
+     * @return JsonResource
+     *
+     * @throws \Throwable
+     */
+    public function toResource(?string $resourceClass = null): JsonResource
+    {
+        if ($resourceClass === null) {
+            return $this->guessResource();
+        }
+
+        return $resourceClass::make($this);
+    }
+
+    /**
+     * Guess the resource class for the model.
+     *
+     * @return JsonResource
+     *
+     * @throws \Throwable
+     */
+    protected function guessResource(): JsonResource
+    {
+        foreach (static::guessResourceName() as $resourceClass) {
+            if (is_string($resourceClass) && class_exists($resourceClass)) {
+                return $resourceClass::make($this);
+            }
+        }
+
+        throw new LogicException(sprintf('Failed to find resource class for model [%s].', get_class($this)));
+    }
+
+    /**
+     * Guess the resource class name for the model.
+     *
+     * @return array<class-string<JsonResource>>
+     */
+    public static function guessResourceName(): array
+    {
+        $modelClass = static::class;
+
+        if (! Str::contains($modelClass, '\\Models\\')) {
+            return [];
+        }
+
+        $relativeNamespace = Str::after($modelClass, '\\Models\\');
+
+        $relativeNamespace = Str::contains($relativeNamespace, '\\')
+            ? Str::before($relativeNamespace, '\\'.class_basename($modelClass))
+            : '';
+
+        $potentialResource = sprintf(
+            '%s\\Http\\Resources\\%s%s',
+            Str::before($modelClass, '\\Models'),
+            strlen($relativeNamespace) > 0 ? $relativeNamespace.'\\' : '',
+            class_basename($modelClass)
+        );
+
+        return [$potentialResource.'Resource', $potentialResource];
+    }
+}

src/Illuminate/Http/Resources/TransformsToResourceCollection.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace Illuminate\Http\Resources;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\Resources\Json\JsonResource;
+use Illuminate\Http\Resources\Json\ResourceCollection;
+use LogicException;
+
+trait TransformsToResourceCollection
+{
+    /**
+     * Create a new resource collection instance for the given resource.
+     *
+     * @param  class-string<JsonResource>|null  $resourceClass
+     * @return ResourceCollection
+     *
+     * @throws \Throwable
+     */
+    public function toResourceCollection(?string $resourceClass = null): ResourceCollection
+    {
+        if ($resourceClass === null) {
+            return $this->guessResourceCollection();
+        }
+
+        return $resourceClass::collection($this);
+    }
+
+    /**
+     * Guess the resource collection for the items.
+     *
+     * @return ResourceCollection
+     *
+     * @throws \Throwable
+     */
+    protected function guessResourceCollection(): ResourceCollection
+    {
+        if ($this->isEmpty()) {
+            return new ResourceCollection($this);
+        }
+
+        $model = $this->items[0] ?? null;
+
+        throw_unless(is_object($model), LogicException::class, 'Resource collection guesser expects the collection to contain objects.');
+
+        /** @var class-string<Model> $className */
+        $className = get_class($model);
+
+        throw_unless(method_exists($className, 'guessResourceName'), LogicException::class, sprintf('Expected class %s to implement guessResourceName method. Make sure the model uses the TransformsToResource trait.', $className));
+
+        foreach ($className::guessResourceName() as $resourceClass) {
+            if (is_string($resourceClass) && class_exists($resourceClass)) {
+                return $resourceClass::collection($this);
+            }
+        }
+
+        throw new LogicException(sprintf('Failed to find resource class for model [%s].', $className));
+    }
+}

src/Illuminate/Pagination/AbstractPaginator.php

@@ -5,6 +5,7 @@
 use Closure;
 use Illuminate\Contracts\Support\CanBeEscapedWhenCastToString;
 use Illuminate\Contracts\Support\Htmlable;
+use Illuminate\Http\Resources\TransformsToResourceCollection;
 use Illuminate\Support\Arr;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Traits\ForwardsCalls;
@@ -21,7 +22,7 @@
  */
 abstract class AbstractPaginator implements CanBeEscapedWhenCastToString, Htmlable, Stringable
 {
-    use ForwardsCalls, Tappable;
+    use ForwardsCalls, Tappable, TransformsToResourceCollection;
 
     /**
      * All of the items being paginated.

tests/Database/DatabaseEloquentResourceCollectionTest.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace Illuminate\Tests\Database;
+
+use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\Resources\Json\JsonResource;
+use Illuminate\Tests\Database\Fixtures\Models\EloquentResourceCollectionTestModel;
+use PHPUnit\Framework\TestCase;
+
+class DatabaseEloquentResourceCollectionTest extends TestCase
+{
+    public function testItCanTransformToExplicitResource()
+    {
+        $collection = new Collection([
+            new EloquentResourceCollectionTestModel(),
+        ]);
+
+        $resource = $collection->toResourceCollection(EloquentResourceCollectionTestResource::class);
+
+        $this->assertInstanceOf(JsonResource::class, $resource);
+    }
+
+    public function testItThrowsExceptionWhenResourceCannotBeFound()
+    {
+        $this->expectException(\LogicException::class);
+        $this->expectExceptionMessage('Failed to find resource class for model [Illuminate\Tests\Database\Fixtures\Models\EloquentResourceCollectionTestModel].');
+
+        $collection = new Collection([
+            new EloquentResourceCollectionTestModel(),
+        ]);
+        $collection->toResourceCollection();
+    }
+
+    public function testItCanGuessResourceWhenNotProvided()
+    {
+        $collection = new Collection([
+            new EloquentResourceCollectionTestModel(),
+        ]);
+
+        class_alias(EloquentResourceCollectionTestResource::class, 'Illuminate\Tests\Database\Fixtures\Http\Resources\EloquentResourceCollectionTestModelResource');
+
+        $resource = $collection->toResourceCollection();
+
+        $this->assertInstanceOf(JsonResource::class, $resource);
+    }
+}
+
+class EloquentResourceCollectionTestResource extends JsonResource
+{
+    //
+}

tests/Database/DatabaseEloquentResourceModelTest.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Illuminate\Tests\Database;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Http\Resources\Json\JsonResource;
+use Illuminate\Tests\Database\Fixtures\Models\EloquentResourceTestResourceModel;
+use Illuminate\Tests\Database\Fixtures\Models\EloquentResourceTestResourceModelWithGuessableResource;
+use PHPUnit\Framework\TestCase;
+
+class DatabaseEloquentResourceModelTest extends TestCase
+{
+    public function testItCanTransformToExplicitResource()
+    {
+        $model = new EloquentResourceTestResourceModel();
+        $resource = $model->toResource(EloquentResourceTestJsonResource::class);
+
+        $this->assertInstanceOf(EloquentResourceTestJsonResource::class, $resource);
+        $this->assertSame($model, $resource->resource);
+    }
+
+    public function testItThrowsExceptionWhenResourceCannotBeFound()
+    {
+        $this->expectException(\LogicException::class);
+        $this->expectExceptionMessage('Failed to find resource class for model [Illuminate\Tests\Database\Fixtures\Models\EloquentResourceTestResourceModel].');
+
+        $model = new EloquentResourceTestResourceModel();
+        $model->toResource();
+    }
+
+    public function testItCanGuessResourceWhenNotProvided()
+    {
+        $model = new EloquentResourceTestResourceModelWithGuessableResource();
+
+        class_alias(EloquentResourceTestJsonResource::class, 'Illuminate\Tests\Database\Fixtures\Http\Resources\EloquentResourceTestResourceModelWithGuessableResourceResource');
+
+        $resource = $model->toResource();
+
+        $this->assertInstanceOf(EloquentResourceTestJsonResource::class, $resource);
+        $this->assertSame($model, $resource->resource);
+    }
+
+    public function testItCanGuessResourceWhenNotProvidedWithNonResourceSuffix()
+    {
+        $model = new EloquentResourceTestResourceModelWithGuessableResource();
+
+        class_alias(EloquentResourceTestJsonResource::class, 'Illuminate\Tests\Database\Fixtures\Http\Resources\EloquentResourceTestResourceModelWithGuessableResource');
+
+        $resource = $model->toResource();
+
+        $this->assertInstanceOf(EloquentResourceTestJsonResource::class, $resource);
+        $this->assertSame($model, $resource->resource);
+    }
+
+    public function testItCanGuessResourceName()
+    {
+        $model = new EloquentResourceTestResourceModel();
+        $this->assertEquals([
+            'Illuminate\Tests\Database\Fixtures\Http\Resources\EloquentResourceTestResourceModelResource',
+            'Illuminate\Tests\Database\Fixtures\Http\Resources\EloquentResourceTestResourceModel'
+        ], $model::guessResourceName());
+    }
+}
+
+class EloquentResourceTestJsonResource extends JsonResource
+{
+    //
+}

tests/Database/Fixtures/Models/EloquentResourceCollectionTestModel.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace Illuminate\Tests\Database\Fixtures\Models;
+
+use Illuminate\Database\Eloquent\Model;
+
+class EloquentResourceCollectionTestModel extends Model
+{
+    //
+}

tests/Database/Fixtures/Models/EloquentResourceTestResourceModel.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Illuminate\Tests\Database\Fixtures\Models;
+
+use Illuminate\Database\Eloquent\Concerns\HasUlids;
+use Illuminate\Database\Eloquent\Model;
+
+class EloquentResourceTestResourceModel extends Model
+{
+    //
+}

tests/Database/Fixtures/Models/EloquentResourceTestResourceModelWithGuessableResource.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Illuminate\Tests\Database\Fixtures\Models;
+
+use Illuminate\Database\Eloquent\Concerns\HasUlids;
+use Illuminate\Database\Eloquent\Model;
+
+class EloquentResourceTestResourceModelWithGuessableResource extends Model
+{
+    //
+}

tests/Pagination/Fixtures/Models/PaginatorResourceTestModel.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Illuminate\Tests\Pagination\Fixtures\Models;
+
+use Illuminate\Database\Eloquent\Concerns\HasUlids;
+use Illuminate\Database\Eloquent\Model;
+
+class PaginatorResourceTestModel extends Model
+{
+    //
+}