README

A variation / interpretation of the Data Transfer Object (DTO) design pattern (Distribution Pattern). A DTO is nothing more than an object that can hold some data. Most commonly it is used for transporting that data between system layers.

Installation

You can install the package via composer

composer require imbue/data-transfer-object

Usage

Introduction
Accessors & Mutators
- Defining A Getter
- Defining A Setter
Serializing Objects & Collections
- Serializing To Arrays
- Serializing To JSON
Collections
Helpers
Example

Introduction

Using getter/setter methods gives the advantage of type hinting all data being set. Thus any data object will be transparent and easy to use without the need of additional documentation, for example the API client you're writing.

Getters & Setters

Defining A Getter

To define a getter, simply create a get...() method on your data object

class BookData extends DataTransferObject
{
    protected $title;
    protected $author;

    /**
     * @return string
     */
    public function getTitle()
    {
        return $this->title;
    }

    /**
     * @return AuthorData
     */
    public function getAuthor(): AuthorData
    {
        return $this->author;
    }
}

Defining A Setter

To define a setters, simply create a set...() method on your data object

class BookData extends DataTransferObject
{
    protected $title;
    protected $author;

    /**
     * @param nullable|string $title
     */
    public function setTitle(?string $title)
    {
        return $this->title;
    }

    /**
     * @param AuthorData $author
     */
    public function setAuthor(AuthorData $author)
    {
        return $this->author;
    }
}

Serializing Objects & Collections

Serializing To Arrays

To convert a value object and its nested objects/collections to an array, you can use the toArray method. This method is recursive, so all attributes will be converted to arrays:

return $dataObject->toArray();

Serializing To JSON

To convert a value object and its nested objects/collections to a JSON object, you can use the toJson method. This method is recursive, so all attributes will be converted into JSON:

return $dataObject->toJson();

Collections

In some cases you may want to have a collection of multiple data objects. By extending the provided DataTransferObjectColletion class, you can easily set up a group of DTOs

$collection = new BooksCollection([
    $bookOne,
    $bookTwo,
    $bookThree
]);

$collection->toArray();

Auto completion for collections

By overriding the current() method and setting the return value, you can enable type hinting.

class BooksCollection extends DataTransferObjectCollection
{
    public function current(): BookData
    {
        return parent::current();
    }
}

foreach ($booksCollection as $bookData) {
    $bookData-> // type hinting 
}

Helpers

There are a few helper methods to provide some extra functionality

only()

$dataObject
    ->only('title')
    ->toArray();

except()

$dataObject
    ->except('title')
    ->toArray();

Immutability

These helpers are immutable, which means they wont affect the original data transfer object.

Example

Using the data objects is made as simple as possible

$book = new BookData();
$book->setTitle('Harry Potter: The Goblet of Fire');

$author = new Author();
// ....

$book->setAuthor($author);

Security

If you discover any security related issues, please use the issue tracker.

Testing

composer test

Credits

This package is based on the data-transfer-object package from Spatie.
Arr class contains functions copied from Laravel's Arr helper.

imbue / data-transfer-object

Maintainers

Details