Add ability to make a field sparse by default

Author: tobyzerner

src/Context.php

@@ -109,11 +109,16 @@ public function sparseFields(Resource $resource): array
         }
 
         $fields = $this->fields($resource);
+        $type = $resource->type();
+        $fieldsParam = $this->queryParam('fields');
 
-        if ($requested = $this->queryParam('fields')[$resource->type()] ?? null) {
+        if (is_array($fieldsParam) && array_key_exists($type, $fieldsParam)) {
+            $requested = $fieldsParam[$type];
             $requested = is_array($requested) ? $requested : explode(',', $requested);
 
             $fields = array_intersect_key($fields, array_flip($requested));
+        } else {
+            $fields = array_filter($fields, fn(Field $field) => !$field->sparse);
         }
 
         return $this->sparseFields[$resource] = $fields;
@@ -122,13 +127,15 @@ public function sparseFields(Resource $resource): array
     /**
      * Determine whether a field has been requested in a sparse fieldset.
      */
-    public function fieldRequested(string $type, string $field, bool $default = true): bool
+    public function fieldRequested(string $type, string $field): bool
     {
-        if ($requested = $this->queryParam('fields')[$type] ?? null) {
-            return in_array($field, explode(',', $requested));
+        $fieldsParam = $this->queryParam('fields');
+
+        if (is_array($fieldsParam) && array_key_exists($type, $fieldsParam)) {
+            return in_array($field, explode(',', $fieldsParam[$type]));
         }
 
-        return $default;
+        return !($this->fields($this->resource($type))[$field]?->sparse ?? null);
     }
 
     /**

src/Schema/Field/Field.php

@@ -18,6 +18,7 @@ abstract class Field
     public bool $nullable = false;
     public ?string $description = null;
     public array $schema = [];
+    public bool $sparse = false;
 
     public function __construct(public readonly string $name)
     {
@@ -57,4 +58,14 @@ public function getSchema(JsonApi $api): array
             'readOnly' => !$this->writable,
         ];
     }
+
+    /**
+     * Only include this field if it is specifically requested.
+     */
+    public function sparse(): static
+    {
+        $this->sparse = true;
+
+        return $this;
+    }
 }