Mapping external API response data

[booni3]

Having looked around the package and other discussions/issues, I see that this package is not necessarily designed with this in mind. However, like a few others, I have come across issues when migrating from the spatie/data-transfer-object package.

Using the tooling provided by these packages to normalise external API data is extremely useful. Especially when the normalised external data matches that of internal Models.

Simplified structure for discussion:

class InvoiceDTO extends Data
{
    public string $id;
    public string $invoice_number;
    public string $currency;
    public CarbonImmutable $date;
    #[DataCollectionOf(LineItemDTO::class)]
    public DataCollection $line_items;
    public ContactDTO $contact;
}

class LineItemDTO extends Data
{
    public string $id;
    public string|null $description;
    public int|null $qty;
    public float|null $unit_cost;
}

class ContactDTO extends Data
{
    public string $id;
    public string $name;
}

In the data-transfer-object package, I would make these abstract classes and then extend them into an XeroInvoiceDTO, XeroInvoiceItemDTO etc., each with its own mapping and normalising functions.

class XeroContactDTO extends ContactDTO
{
    public function __construct(
        #[MapInputName('ContactID')]
        public string $id,
        #[MapInputName('Name')]
        public string $name,
    ) {
        $this->state = $this->normaliseState($this->state);
    }
    
    ...
}

This still works to some degree, but has already failed in these areas:

• Typed properties cannot be extended. So ContactDTO cannot be extended to XeroContactDTO
• Abstract classes can't be referenced within Livewire.
• Making the base class not abstract has issues on component refresh. Livewire does not know which extended class should be used.
• The extended class is redundant once the data has been normalised.
• ...Way more I have not come across yet.

I realise this package has not been designed with this in mind. However, quite a few people from data-transfer-object use it this way. I have not got into the validation side of things, but the mapping, casts and data object tooling make this work amazingly well, i.e. XeroInvoice::from($xeroApiResponse->toArray())

For now, I am doing the following, however I would love to discuss better ways:

1. Changing the DTO classes to final. I don't want these extended for the reasons above. I realise there may be instances where you would like to extend.

final class InvoiceDTO extends Data

2. Pass the service-specific DTO into the main one, which works well for this use.

return InvoiceDTO::from(
    XeroInvoiceDTO::from($apiResponse->toStringArray())
);