feat: global config

Author: Ark4ne

composer.json

@@ -37,5 +37,12 @@
       "email": "gui.allegret@gmail.com"
     }
   ],
+  "extra": {
+    "laravel": {
+      "providers": [
+        "Ark4ne\\JsonApi\\Providers\\LaravelJsonApiProvider"
+      ]
+    }
+  },
   "minimum-stability": "dev"
 }

config/jsonapi.php

@@ -0,0 +1,59 @@
+<?php
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Describer
+    |--------------------------------------------------------------------------
+    |
+    | Config for described notation
+    |
+    */
+    'describer' => [
+        /*
+        |--------------------------------------------------------------------------
+        | Nullable
+        |--------------------------------------------------------------------------
+        |
+        | Value nullable by default.
+        |
+        */
+        'nullable' => true,
+
+        /*
+        |--------------------------------------------------------------------------
+        | Date format
+        |--------------------------------------------------------------------------
+        |
+        | Default date format.
+        |
+        */
+        'date' => DateTimeInterface::ATOM,
+
+        /*
+        |--------------------------------------------------------------------------
+        | Decimal precision
+        |--------------------------------------------------------------------------
+        |
+        | Decimal precision for float value.
+        | 'null' for disable.
+        |
+        */
+        'precision' => null,
+    ],
+
+    'relationship' => [
+        /*
+        |--------------------------------------------------------------------------
+        | When Included
+        |--------------------------------------------------------------------------
+        |
+        | @see whenIncluded()
+        |
+        | false => relationship data will always be loaded and set to relation data
+        | true  => relationship data will not be loaded until relationship is set to include
+        |
+        */
+        'when-included' => false,
+    ],
+];

readme.md

@@ -11,8 +11,16 @@ A Lightweight [{JSON:API}](https://jsonapi.org/) Resource for Laravel.
 composer require ark4ne/laravel-json-api
 ```
 
+# Config
+| Path                         | Type                     | Description                                                                             |
+|------------------------------|--------------------------|-----------------------------------------------------------------------------------------|
+| `describer.nullable`         | `bool`                   | For describer notation, defined if a value is nullable by default.                      |
+| `describer.date`             | `string` datetime format | For describer notation, defined default date time format.                               |
+| `describer.precision`        | `int` \ `null`           | For describer notation, decimal precision for float value. `null` for disable rounding. |
+| `relationship.when-included` | `bool`                   | Allow to disabled by default the loading of relationship data.                          |
+
 # Usage
-This package is an specialisation of Laravel's `JsonResource` class.
+This package is a specialisation of Laravel's `JsonResource` class.
 All the underlying API's are still there, thus in your controller you can still interact
 with `JsonApiResource` classes as you would with the base `JsonResource` class
 
@@ -42,7 +50,7 @@ class UserFetchRequest extends FormRequest
 }
 ```
 
-`Rules\Includes` will validate the include to exactly match the UserResource schema (determined by the relationships).
+`Rules\Includes` will validate the `include` to exactly match the UserResource schema (determined by the relationships).
 
 
 ### Fields validation
@@ -62,7 +70,7 @@ class UserFetchRequest extends FormRequest
 }
 ```
 
-`Rules\Fields` will validate the fields to exactly match the UserResource schema (determined by the attributes and relationships).
+`Rules\Fields` will validate the `fields` to exactly match the UserResource schema (determined by the attributes and relationships).
 
 
 ### Customize validation message
@@ -381,13 +389,15 @@ UserResource::collection(User::all()); // => JsonApiCollection
 ## Described notation
 
 ### Value methods
-| Method    | Description              |
-|-----------|--------------------------|
-| `bool`    | Cast to boolean          |
-| `integer` | Cast to integer          |
-| `float`   | Cast to float            |
-| `array`   | Cast to array            |
-| `mixed`   | Don't cast, return as is |
+| Method    | Description                              |
+|-----------|------------------------------------------|
+| `bool`    | Cast to boolean                          |
+| `integer` | Cast to integer                          |
+| `float`   | Cast to float                            |
+| `string`  | Cast to string                           |
+| `date`    | Cast to date, allow to use custom format |
+| `array`   | Cast to array                            |
+| `mixed`   | Don't cast, return as is                 |
 
 ### Relation methods
 | Method  | Description                                                       |

src/Descriptors/Relations/Relation.php

@@ -4,6 +4,7 @@
 
 use Ark4ne\JsonApi\Descriptors\Describer;
 use Ark4ne\JsonApi\Resources\Relationship;
+use Ark4ne\JsonApi\Support\Config;
 use Closure;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Http\Request;
@@ -17,7 +18,7 @@ abstract class Relation extends Describer
 {
     protected ?Closure $links = null;
     protected ?Closure $meta = null;
-    protected bool $whenIncluded = false;
+    protected bool $whenIncluded;
 
     /**
      * @param class-string<\Ark4ne\JsonApi\Resources\JsonApiResource|\Ark4ne\JsonApi\Resources\JsonApiCollection> $related
@@ -27,6 +28,7 @@ public function __construct(
         protected string $related,
         protected null|string|Closure $relation
     ) {
+        $this->whenIncluded = Config::$whenIncluded;
     }
 
     /**

src/Descriptors/Values/Value.php

@@ -3,6 +3,7 @@
 namespace Ark4ne\JsonApi\Descriptors\Values;
 
 use Ark4ne\JsonApi\Descriptors\Describer;
+use Ark4ne\JsonApi\Support\Config;
 use Ark4ne\JsonApi\Support\Fields;
 use Closure;
 use Illuminate\Database\Eloquent\Model;
@@ -14,11 +15,12 @@
  */
 abstract class Value extends Describer
 {
-    protected bool $nullable = true;
+    protected bool $nullable;
 
     public function __construct(
         protected null|string|Closure $attribute
     ) {
+        $this->nullable = Config::$nullable;
     }
 
     public function retriever(): string|Closure|null

src/Descriptors/Values/ValueDate.php

@@ -2,6 +2,8 @@
 
 namespace Ark4ne\JsonApi\Descriptors\Values;
 
+use Ark4ne\JsonApi\Support\Config;
+use Closure;
 use DateTime;
 use DateTimeInterface;
 
@@ -11,7 +13,14 @@
  */
 class ValueDate extends Value
 {
-    protected string $format = DateTimeInterface::ATOM;
+    protected string $format;
+
+    public function __construct(string|Closure|null $attribute)
+    {
+        parent::__construct($attribute);
+
+        $this->format = Config::$date;
+    }
 
     public function format(string $format): static
     {
@@ -24,7 +33,7 @@ public function format(string $format): static
      */
     public function value(mixed $of): string
     {
-        if($of === null) {
+        if ($of === null) {
             return (new DateTime("@0"))->format($this->format);
         }
         if ($of instanceof DateTimeInterface) {

src/Descriptors/Values/ValueFloat.php

@@ -2,13 +2,23 @@
 
 namespace Ark4ne\JsonApi\Descriptors\Values;
 
+use Ark4ne\JsonApi\Support\Config;
+use Closure;
+
 /**
  * @template T as \Illuminate\Database\Eloquent\Model
  * @extends Value<T>
  */
 class ValueFloat extends Value
 {
-    protected int $precision;
+    protected int|null $precision;
+
+    public function __construct(string|Closure|null $attribute)
+    {
+        parent::__construct($attribute);
+
+        $this->precision = Config::$precision;
+    }
 
     public function precision(int $precision): static
     {

src/Providers/LaravelJsonApiProvider.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Ark4ne\JsonApi\Providers;
+
+use Ark4ne\JsonApi\Support\Config;
+use Illuminate\Support\ServiceProvider;
+
+class LaravelJsonApiProvider extends ServiceProvider
+{
+    public function register(): void
+    {
+        $this->publishes([
+            __DIR__ . '/../../config/jsonapi.php' => config_path('jsonapi.php')
+        ], 'config');
+    }
+
+    public function boot(): void
+    {
+        Config::boot();
+    }
+}

src/Support/Config.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Ark4ne\JsonApi\Support;
+
+use DateTimeInterface;
+
+class Config
+{
+    public static bool $nullable = true;
+
+    public static string $date = DateTimeInterface::ATOM;
+
+    public static bool $whenIncluded = false;
+
+    public static int|null $precision = null;
+
+    public static function boot(): void
+    {
+        self::$nullable = config('jsonapi.describer.nullable', self::$nullable);
+        self::$date = config('jsonapi.describer.date', self::$date);
+        self::$precision = config('jsonapi.describer.precision', self::$precision);
+        self::$whenIncluded = config('jsonapi.relationship.when-included', self::$whenIncluded);
+    }
+}

tests/TestCase.php

@@ -2,10 +2,18 @@
 
 namespace Test;
 
+use Ark4ne\JsonApi\Providers\LaravelJsonApiProvider;
 use Illuminate\Foundation\Testing\RefreshDatabase;
 use Orchestra\Testbench\TestCase as BaseTestCase;
 
 class TestCase extends BaseTestCase
 {
     use RefreshDatabase;
+
+    protected function getPackageProviders($app): array
+    {
+        return [
+            LaravelJsonApiProvider::class,
+        ];
+    }
 }