[PRO] PropertyForMorph should document as a constant value

[alec-superfile]

https://spatie.be/docs/laravel-data/v4/as-a-data-transfer-object/abstract-data

It would be amazing if Scramble could document the PropertyForMorph attribute as a constant for DTOs that extend an Abstract class. I'll also spend some time looking into how it can be made into an extension if possible.

Example:

abstract class AssetData extends Resource implements PropertyMorphableData
{
    public string $id;
    public string $name;
    #[PropertyForMorph]
    public Type $type;

    /**
     * Determine which data class to use when morphing the abstract class.
     *
     * @param array $properties The key values of the object.
     */
    public static function morph(array $properties): ?string
    {
        return match ($properties['type']) {
            Type::FILE => FileData::class, // Value is "file"
            Type::FOLDER => FolderData::class, // "folder"
            Type::SHORTCUT => ShortcutData::class, // "shortcut"
            default => null
        };
    }
}

class ShortcutData extends AssetData
{
    /**
     * The data constructor for a shortcut asset.
     *
     * @param string $asset_id The asset ID if it's a shortcut.
     */
    public function __construct(
        public string $asset_id,
        #[AutoWhenLoadedLazy('asset')]
        public Lazy|FileData $asset,
    ) {
    }
}

Outputs to something like

ShortcutData:
      type: object
      properties:
      // ...
        type:
          type: string
          const: shortcut
      // ...

FileData:
      type: object
      properties:
      // ...
        type:
          type: string
          const: file
      // ...

FolderData:
      type: object
      properties:
      // ...
        type:
          type: string
          const: folder
      // ...

It would be useful for our typescript clients to be able to narrow down which schema by checking the type instead of one of its unique properties.

[romalytvynenko]

@alec-superfile doesn't it already document it like so?

[alec-superfile]

Its documenting it as a ref (maybe because its an enum?)

"type": {
    "$ref": "#/components/schemas/AssetType"
},

[romalytvynenko]

@alec-superfile indeed!

This is how it works with strings: https://scramble.dedoc.co/packages/laravel-data#abstract-data

(in the documentation, JSON schema is using enum, but with some of the recent releases, const will be used)

In your example, I think it is pretty safe to document enum property (Type $type in your case) as string.

Quick question – Scramble allows you to add the description to your enum cases. Is that something you'd wish to see in the documentation for type property? But it is hard for me to imagine, how that should work...

[alec-superfile]

Got it, we prefer to strongly type using enums instead of magic strings in our codebase— would it be possible to have the schema for storing use the typed enum (for a POST request) but the schema for viewing a constant string?

[romalytvynenko]

Yeah, I think this is the most obvious and predictable implementation: in case enum is used with PropertyForMorph, Scramble will document is as strings (like you expect). If that enum is used anywhere else - it will be its own schema.

[romalytvynenko]

@alec-superfile done!

Please bump dedoc/scramble-pro to 0.9.13