Definition File

Definition Structure

The Transfer Object definition is a YML file with name matching pattern *.transfer.yml.

Definition file can include one or more Transfer Object definitions:

• Each root level represents a new Transfer Object name.
• The second level represents property names.
• The third level represents the property type and supporting keys:
  • type
  • collectionType
  • enumType
  • dateTimeType
  • numberType
  • required
  • protected
  • attributes

Example

Customer:
    firstName:
        type: string
    lastName:
        type: string

Schema

In order to use schema please add on the top of definition files the following:

# $schema: https://raw.githubusercontent.com/picamator/transfer-object/main/schema/definition.schema.json

Definition Keys

Type

The type key supports the following PHP built-in types:

• bool
• true
• false
• int
• float
• string
• array
• ArrayObject

Tip

The type key can include the name of the embeded Transfer Object (without the Transfer suffix).

Warning

Union e.g string|bool and Intersection types e.g. CustomerInterface&Customer, are not supported.

Example

Product:
  sku:
    type: string
  details:
    type: Details

Where Details is a Transfer Object name.

DocBlock

For the types array and ArrayObject DocBlock syntax supported:

• array<bool>
• array<int,bool>
• array<string,bool>
• array<int>
• array<int,int>
• array<string,int>
• array<float>
• array<int,float>
• array<string,float>
• array<string>
• array<int,string>
• array<string,string>
• array<mixed>
• array<int,mixed>
• array<string,mixed>
• array<string,array<int,string>>
• ArrayObject<bool>
• ArrayObject<int,bool>
• ArrayObject<string,bool>
• ArrayObject<int>
• ArrayObject<int,int>
• ArrayObject<string,int>
• ArrayObject<float>
• ArrayObject<int,float>
• ArrayObject<string,float>
• ArrayObject<string>
• ArrayObject<int,string>
• ArrayObject<string,string>
• ArrayObject<mixed>
• ArrayObject<int,mixed>
• ArrayObject<string,mixed>
• ArrayObject<string,array<int,string>>

Tip

Basically any text between <> is allowed.

Collection Type

The collectionType key should include the Transfer Object name without the Transfer suffix.

Example

Agent:
  merchants:
    collectionType: Merchant

Enum Type

The enumType key supports only BakedEnum and should include fully-qualified class name.

Example

Merchant:
  country:
    enumType: "Picamator\\Doc\\Samples\\TransferObject\\Enum\\CountryEnum"

The enumType key also supports alias.

Merchant:
  country:
    enumType: "Picamator\\Doc\\Samples\\TransferObject\\Enum\\CountryEnum as CountryEnumAlias"

DateTime Type

The dateTimeType key supports DateTimeInterface implementation such us DateTime, DateTimeImmutable, or any of the sub-classes with fully-qualified class name.

Example

Merchant:
  createdAt:
    dateTimeType: "DateTimeImmutable"
  updatedAt:
    dateTimeType: "DateTime"

The dateTimeType key also supports aliases.

Number Type

The numberType key supports arbitrary precision mathematic class BcMath\Number.

Example

Product:
  price:
    numberType: "BcMath\\Number"

Required

The required key doesn't have any value. It is marking a property as not null.

By default the following types are not nullable:

• ArrayObject
• array
• Transfer Object collections

Example

Merchant:
  merchantReference:
    type: string
    required:
  isActive:
    type: bool
    required:

Protected

The protected key doesn't have any value. It is adding asymmetric protected(set) visibility.

Example

Credentials:
  login:
    type: string
    protected:
  token:
    type: string
    protected:

Attributes

The key attributes is an array where each of element is fully-qualified property attribute class name.

Example

Customer:
  email:
    type: string
    attributes:
      - "\\Symfony\\Component\\Validator\\Constraints\\NotBlank"
      - "\\Symfony\\Component\\Validator\\Constraints\\Email"

For Symfony validation shortcut can be used sf-assert:.

Customer:
  email:
    type: string
    attributes:
      - "sf-assert:NotBlank"
      - "sf-assert:Email"

Advanced Usage

Multi-Module Transfer Object

The basic definition file is built to hold all Transfer Objects in one namespace.

In cases where each application module holds its own Transfer Objects and requires cross-module connections, the type and collectionType fields should contain the full namespace, optionally with a namespace alias.

Example

Let's assume there are two Transfer Objects:

1. MyShop\Cart\Generated\CartTransfer
2. MyShop\Customer\Generated\CustomerTransfer

and the task is to create a new Transfer Object CheckoutTransfer in MyShop\Checkout to hold both CartTransfer and CustomerTransfer.

The MyShop\Checkout should contain the following definition file:

Checkout:
  customer:
    type: "MyShop\\Customer\\Generated\\CustomerTransfer as CustomerAlias"
  cart:
    type: "MyShop\\Cart\\Generated\\CartTransfer"

Important: The namespace should be in double quotes, containing full Transfer Object name with the Transfer suffix.

Running the Transfer Object generation console commands builds CheckoutTransfer with non-nullable properties: customer and cart. Using the full namespace enforces the use of non-nullable rules.

The alias CustomerAlias is helpful when there are multiple objects with the same name used in the Transfer Object.

Custom Transfer Object

Transfer Object supports connecting custom Data Transfer Objects or third-party DTOs such as Spatie Laravel Data or Spryker Transfer.

To integrate a custom Transfer Object, the steps should be followed:

1. The custom Transfer Object should implement Picamator\TransferObject\Transfer\TransferInterface interface.
2. Optionally, Transfer Object can use one of the available adapters:
   • Picamator\TransferObject\Transfer\Adapter\DummyTransferAdapterTrait
   • Picamator\TransferObject\Transfer\Adapter\TransferAdapterTrait

Example

Let's consider there is a custom Data Transfer Object:

class CredentialsData
{
    public string $login {
        get => $this->login;
        set => $this->login = $value;
    }

    public string $token {
        get => $this->token;
        set => $this->token = $value;
    }
}

After implementing the interface and dummy trait, it looks like:

use Picamator\TransferObject\Transfer\Adapter\DummyTransferAdapterTrait;
use Picamator\TransferObject\Transfer\TransferInterface;

class CredentialsData implements TransferInterface
{
    use DummyTransferAdapterTrait;

    public string $login {
        get => $this->login;
        set => $this->login = $value;
    }

    public string $token {
        get => $this->token;
        set => $this->token = $value;
    }
}

Finally, the custom Data Transfer Object can be registered in the definition file:

Customer:
  credentials:
    type: "MyShop\\Customer\\TDO\\CredentialsData"