feat: add ConditionallyLoadsAttributes with <whenIncluded> method

Author: Ark4ne

src/Concerns/ConditionallyLoadsAttributes.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Ark4ne\JsonApi\Resource\Concerns;
+
+use Ark4ne\JsonApi\Resource\Support\Includes;
+use Illuminate\Http\Request;
+
+trait ConditionallyLoadsAttributes
+{
+    /**
+     * Retrieve a relationship if it has been included.
+     *
+     * @template T
+     *
+     * @param \Illuminate\Http\Request $request
+     * @param string                   $type
+     * @param T                        $value
+     *
+     * @return \Illuminate\Http\Resources\MissingValue|T
+     */
+    protected function whenIncluded(Request $request, string $type, mixed $value)
+    {
+        return $this->when(Includes::include($request, $type), $value);
+    }
+}

src/JsonApiCollection.php

@@ -10,6 +10,7 @@
 class JsonApiCollection extends ResourceCollection implements Resourceable
 {
     use Concerns\Relationize,
+        Concerns\ConditionallyLoadsAttributes,
         Concerns\ToResponse;
 
     public $collects;

src/JsonApiResource.php

@@ -8,6 +8,7 @@
 abstract class JsonApiResource extends JsonResource implements Resourceable
 {
     use Concerns\Relationize,
+        Concerns\ConditionallyLoadsAttributes,
         Concerns\Identifier,
         Concerns\Attributes,
         Concerns\Relationships,

tests/Unit/Concerns/ConditionallyLoadsAttributesTest.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Test\Unit\Concerns;
+
+use Ark4ne\JsonApi\Resource\Concerns\ConditionallyLoadsAttributes;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+use Illuminate\Http\Resources\MissingValue;
+use Test\Support\Reflect;
+use Test\TestCase;
+
+class ConditionallyLoadsAttributesTest extends TestCase
+{
+    private function dataWhenInclude()
+    {
+        return [
+            [false, 'test', []],
+            [true, 'test', ['test']]
+        ];
+    }
+
+    /**
+     * @dataProvider dataWhenInclude
+     */
+    public function testWhenInclude($expected, $property, $query)
+    {
+        $request = new Request(['include' => implode(',', $query)]);
+
+        $stub = new class(null) extends JsonResource {
+            use ConditionallyLoadsAttributes;
+        };
+
+        $this->assertEquals(
+            $expected ?: new MissingValue,
+            Reflect::invoke($stub, 'whenIncluded', $request, $property, true)
+        );
+    }
+}