Strange required property in JsonResource

[apasquini95]

Hi everyone, I'm facing a strange issue regarding required properties in JsonResources even if they are loaded using the Laravel syntax $this->when(...). I have a resource which wraps a class that has a super generic property that accepts all kinds of items:

class MyDto
{
   /**
    * Summary of props
    * @var array<string, mixed>
    */
   public array $props;
   
   /**
    * Create a new class instance.
    */
   public function __construct(
       array $props
   ) {
       $this->props = $props;
   }
}

The resource simply adds the corresponding keys only when the original dto has that key:

/**
 * Summary of MyResource.
 * @property MyDto $resource
 */
class MyResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        /**
         * @var array {
         *      prop_1: int,
         *      prop_2?: bool
         *  } $props
         */
        $props = $this->resource->props;

        return [
            /** @var int */
            'required_prop'    => $props['prop_1'],

            /** @var bool */
            'conditional_prop' => $this->when(
                array_key_exists('prop_2', $props),
                function () use ($props) {

                    return $props['prop_2'];
                }
            )
        ];
    }
}

I do not expect Scramble to know the type of data this array $props could contain, that's why I specified explicitly the type, but why conditional_prop has been considered required in the openapi specification?

{
    "openapi": "3.1.0",
    "info": {
        "title": "Laravel",
        "version": "0.0.1"
    },
    "servers": [
        {
            "url": "http://localhost/api"
        }
    ],
    "paths": {
        "/": {
            "get": {
                "operationId": "test_route",
                "tags": [
                    "My"
                ],
                "responses": {
                    "200": {
                        "description": "`MyResource`",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/MyResource"
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "MyResource": {
                "type": "object",
                "properties": {
                    "required_prop": {
                        "type": "integer"
                    },
                    "conditional_prop": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "required_prop",
                    "conditional_prop"        // Why is it required?
                ],
                "title": "MyResource"
            }
        }
    }
}

Am I missing something or maybe I could write the resource differently?
You can reproduce it in this public repository
https://github.com/apasquini95/demo_scramble/tree/bug_required_when

[romalytvynenko]

@apasquini95 this is because you have overwritten the type of that property using var annotation

[apasquini95]

So there's no way to make it not required if you overwrite by hand the type?

[romalytvynenko]

Try MissingValue|bool

(you need to either "import" MissingValue, or use it with fully qualified name)

[romalytvynenko]

Or you can add a type hint to the function:

return [
            /** @var int */
            'required_prop'    => $props['prop_1'],

            'conditional_prop' => $this->when(
                array_key_exists('prop_2', $props),
                function () use ($props): bool {

                    return $props['prop_2'];
                }
            )
        ];

[apasquini95]

I still think there's something strange, now I used added other properties in the resource, even faking the return type just to see if the phpdoc overwrites the real type:

public function toArray(Request $request): array
{
    /**
     * @var array {
     *      prop_1: int,
     *      prop_2?: bool
     *  } $props
     */
    $props = $this->resource->props;

    return [
        /** @var bool */
        'conditional_prop' => $this->when(
            array_key_exists('prop_2', $props),
            function () use ($props) {
                return (bool) $props['prop_2'];
            }
        ),
        
        /** @var bool */
        'conditional_prop_but_required' => $this->when(
            array_key_exists('prop_2', $props),
            function () use ($props) {
                return $props['prop_2'];
            }
        ),

        /** @var bool */
        'fake_bool_prop'   => $this->when(
            array_key_exists('prop_1', $props),
            function () use ($props) {
                return strlen((string) $props['prop_1']);
            }
        ),
    ];
}

And the resulting specification:

{
  "MyResource": {
      "type": "object",
      "properties": {
          "conditional_prop": {
              "type": "boolean"
          },
          "conditional_prop_but_required": {
              "type": "boolean"
          },
          "fake_bool_prop": {
              "type": "boolean"
          }
      },
      "required": [
          "conditional_prop_but_required"
      ],
      "title": "MyResource"
  }
}

I do not understand if there's a sort of precedence, but in this example it doesn't seem directly related to the phpdoc, otherwise I would expected fake_bool_prop to have been considered required too. I updated the repository branch, if you want to see it in action.

[romalytvynenko]

@apasquini95 Interesting indeed!

Feel free to create the issue and repro repo!