feat: v1.0.0 - Resource schema

Author: Ark4ne

CHANGELOG-1.0.md

@@ -0,0 +1,36 @@
+Release note
+============
+
+# v1.0.0
+### Added
+- `Schema` trait implement method `schema` on `JsonApiResource` and `JsonApiCollection`
+- `Relationize::relationship` static method which allow to create relation for resource (like : `PostResource::relationship(fn() => $this->posts)`)
+
+
+### Breaking change
+- `Relationship::construct` signature has change for :
+```php 
+public function __construct(
+  protected string $resource, // represent class-string of resource  
+  protected Closure $value,   // MUST be a closure which return real value
+  protected ?Closure $links = null,
+  protected ?Closure $meta = null
+)
+```
+
+- `JsonApiResource`
+  - `construct` can't be overwrited
+  - `toAttributes` **SHOULD** return an `array<string, Closure>`
+  - `toRelationships` **MUST** return an `array<string, Relationship>`
+
+
+- `JsonApiCollection`
+    - `construct` can't be overwrited
+
+
+- `Resourceable`
+  - `toArray` second parameter has been changed from `false` to `true`, and comportment has been inverted. 
+
+
+- `Relationize`
+  - `asRelationship` has been deleted

src/Concerns/Attributes.php

@@ -12,13 +12,13 @@ trait Attributes
      *
      * @param \Illuminate\Http\Request $request
      *
-     * @return array<string, mixed>
+     * @return array<string, Closure>
      *
      * ```
      * return [
-     *     'name' => $this->name,
+     *     'name' => fn() => $this->name,
      *     // with laravel conditional attributes
-     *     'secret' => $this->when($request->user()->isAdmin(), 'secret-value'),
+     *     'secret' => fn() => $this->when($request->user()->isAdmin(), 'secret-value'),
      * ];
      * ```
      */
@@ -34,7 +34,11 @@ protected function toAttributes(Request $request): iterable
      */
     private function requestedAttributes(Request $request): array
     {
-        $attributes = $this->filter(collect($this->toAttributes($request))->toArray());
+        $attributes = collect($this->toAttributes($request))
+            ->map(fn($value) => value($value))
+            ->toArray();
+
+        $attributes = $this->filter($attributes);
 
         $fields = Fields::get($request, $this->toType($request));
 

src/Concerns/Identifier.php

@@ -2,6 +2,7 @@
 
 namespace Ark4ne\JsonApi\Resource\Concerns;
 
+use Illuminate\Database\Eloquent\Model;
 use Illuminate\Http\Request;
 use Illuminate\Support\Str;
 
@@ -36,6 +37,10 @@ protected function toType(Request $request): string
      */
     protected function toIdentifier(Request $request): int|string
     {
+        if ($this->resource instanceof Model) {
+            return $this->resource->getKey();
+        }
+
         return $this->id;
     }
 

src/Concerns/Relationize.php

@@ -8,17 +8,17 @@
 trait Relationize
 {
     /**
-     * Transform JSON:API resource as relationship
+     * @param \Closure      $value
+     * @param \Closure|null $links
+     * @param \Closure|null $meta
      *
-     * @param iterable|\Closure $links
-     * @param iterable|\Closure $meta
-     *
-     * @return \Ark4ne\JsonApi\Resource\Relationship
+     * @return \Ark4ne\JsonApi\Resource\Relationship<static>
      */
-    public function asRelationship(
-        iterable|Closure $links = [],
-        iterable|Closure $meta = []
+    public static function relationship(
+        Closure $value,
+        ?Closure $links = null,
+        ?Closure $meta = null
     ): Relationship {
-        return new Relationship($this, $links, $meta);
+        return new Relationship(static::class, $value, $links, $meta);
     }
 }

src/Concerns/Relationships.php

@@ -13,15 +13,15 @@ trait Relationships
      *
      * @param \Illuminate\Http\Request $request
      *
-     * @return array<string, <Closure():<Relationship> | Relationship>>
+     * @return array<string, Relationship>
      *
      * ```
      * return [
-     *     'avatar' => AvatarResource::make($this->avatar),
-     *     // with lazy evaluation
-     *     'posts' => fn () => PostResource::collection($this->posts),
+     *     'avatar' => AvatarResource::relationship(fn() => $this->avatar),
+     *     // as collection
+     *     'posts' => PostResource::relationship(fn() => $this->posts)->asCollection(),
      *     // with laravel conditional relationships
-     *     'comments' => $this->when($this->canComments(), fn() => fn() => CommentResource::collection($this->comments),
+     *     'comments' => CommentResource::relationship(fn() => $this->when($this->canComments(), fn() => $this->comments))->asCollection(),
      * ];
      * ```
      */
@@ -33,19 +33,14 @@ protected function toRelationships(Request $request): iterable
     private function requestedRelationships(Request $request): array
     {
         $relations = [];
-        $relationships = $this->toRelationships($request);
 
-        foreach ($this->filter($relationships) as $name => $relationship) {
-            $relationship = value($relationship);
+        foreach ($this->toRelationships($request) as $name => $relationship) {
+            $relationship->forRelation($name);
 
-            if (!($relationship instanceof Relationship)) {
-                $relationship = new Relationship($relationship);
-            }
-
-            $minimal = !Includes::include($request, $name);
+            $included = Includes::include($request, $name);
 
             $relations[$name] = Includes::through($name, fn() => $this->mapRelationship(
-                $minimal,
+                $included,
                 $request,
                 $relationship
             ));
@@ -55,11 +50,11 @@ private function requestedRelationships(Request $request): array
     }
 
     private function mapRelationship(
-        bool $minimal,
+        bool $included,
         Request $request,
         Relationship $relationship
     ): array {
-        $resource = $relationship->toArray($request, $minimal);
+        $resource = $relationship->toArray($request, $included);
 
         if (isset($resource['included'])) {
             $this->with['included'] = array_merge(

src/Concerns/Schema.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Ark4ne\JsonApi\Resource\Concerns;
+
+use Ark4ne\JsonApi\Resource\JsonApiCollection;
+use Ark4ne\JsonApi\Resource\Support\FakeModel;
+use Illuminate\Http\Request;
+
+trait Schema
+{
+    private static array $schemas = [];
+
+    public static function schema(Request $request = null): object
+    {
+        $request ??= new Request;
+
+        $resource = new static(new FakeModel);
+
+        if ($resource instanceof JsonApiCollection) {
+            return $resource->collects::schema($request);
+        }
+
+        if (isset(self::$schemas[static::class])) {
+            return self::$schemas[static::class];
+        }
+
+        $schema = (object)[
+            'type' => null,
+            'fields' => [],
+            'relationships' => [],
+        ];
+
+        self::$schemas[static::class] = $schema;
+
+        $schema->type = $resource->toType($request);
+        $schema->fields = array_keys($resource->toAttributes($request));
+
+        foreach ($resource->toRelationships($request) as $name => $relation) {
+            $schema->relationships[$name] = $relation->getResource()::schema();
+        }
+
+        return self::$schemas[static::class];
+    }
+}

src/JsonApiCollection.php

@@ -10,7 +10,7 @@
 class JsonApiCollection extends ResourceCollection implements Resourceable
 {
     use Concerns\Relationize,
-        Concerns\ConditionallyLoadsAttributes,
+        Concerns\Schema,
         Concerns\ToResponse;
 
     public $collects;
@@ -23,25 +23,25 @@ class JsonApiCollection extends ResourceCollection implements Resourceable
      *
      * @return void
      */
-    public function __construct($resource, ?string $collects = null)
+    final public function __construct($resource, ?string $collects = null)
     {
         $this->collects = $collects ?: $this->collects;
 
         parent::__construct($resource);
     }
 
-    public function toArray($request, bool $minimal = false): array
+    public function toArray($request, bool $included = true): array
     {
         $data = [];
 
         $base = collect($this->with)->toArray();
         foreach ($this->collection as $resource) {
-            $data[] = $resource->toArray($request, $minimal);
+            $data[] = $resource->toArray($request, $included);
 
             if ($resource instanceof JsonResource) {
                 $with = collect($resource->with($request))->toArray();
 
-                if ($minimal) {
+                if (!$included) {
                     unset($with['included']);
                 }
 

src/JsonApiResource.php

@@ -8,22 +8,27 @@
 abstract class JsonApiResource extends JsonResource implements Resourceable
 {
     use Concerns\Relationize,
-        Concerns\ConditionallyLoadsAttributes,
         Concerns\Identifier,
         Concerns\Attributes,
         Concerns\Relationships,
         Concerns\Links,
         Concerns\Meta,
+        Concerns\Schema,
         Concerns\ToResponse;
 
-    public function toArray($request, bool $minimal = false): array
+    final public function __construct($resource)
+    {
+        parent::__construct($resource);
+    }
+
+    public function toArray($request, bool $included = true): array
     {
         $data = [
             'id' => $this->toIdentifier($request),
             'type' => $this->toType($request),
         ];
 
-        if (!$minimal) {
+        if ($included) {
             $data += [
                 'attributes' => $this->requestedAttributes($request),
                 'relationships' => $this->requestedRelationships($request),