Download the PHP package aedart/dto without Composer

Deprecated - Data Transfer Object (DTO)

Package has been replaced by aedart/athenaeum

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 for transporting that data between systems, e.g. a client and a server.

This package provides an abstraction for such DTOs.

If you don't know about DTOs, I recommend you to read Martin Fowler's description of DTO, and perhaps perform a few Google searches about this topic.

Contents

• When to use this
• How to install
• Quick start
• Advanced usage
• Contribution
• Acknowledgement
• Versioning
• License

When to use this

• When there is a strong need to interface DTOs, e.g. what properties must be available via getters and setters
• When you need to encapsulate data that needs to be communicated between systems and or component instances

Nevertheless, using DTOs can / will increase complexity of your project. Therefore, you should only use it, when you are really sure that you need them.

How to install

This package uses composer. If you do not know what that is or how it works, I recommend that you read a little about, before attempting to use this package.

Quick start

Custom Interface for your DTO

Start off by creating an interface for your DTO. Below is an example for a simple Person interface

Concrete implementation of your DTO

Create a concrete implementation of your interface. Let it extend the default DataTransferObject abstraction.

Now you are ready to use the DTO. The following sections will highlight some of the usage scenarios.

Property overloading

Each defined property is accessible in multiple ways, if a getter and or setter method has been defined for that given property.

For additional information, please read about Mutators and Accessor, PHP's overloading, and PHP's Array-Access

Tip: PHPDoc's property-tag

If you are using a modern IDE, then it will most likely support PHPDoc.

By adding a @property tag to your interface or concrete implementation, your IDE will be able to auto-complete the overloadable properties.

Populating via an array

You can populate your DTO using an array.

If you are extending the default DTO abstraction, then you can also pass in an array in the constructor

Export properties to array

Each DTO can be exported to an array.

Serialize to Json

All DTOs are Json serializable, meaning that they inherit from the JsonSerializable interface. This means that when using json_encode(), the DTO automatically ensures that its properties are serializable by the encoding method.

The above example will output the following;

You can also perform json serialization directly on the DTO, by invoking the toJson() method.

Advanced usage

Inversion of Control (IoC) / Dependency Injection

In this interpretation of the DTO design pattern, each instance must hold a reference to an IoC service container.

If you do not know what this means or how this works, please start off by reading the wiki-article about it.

Bootstrapping a service container

If you are using this package inside a Laravel application, then you can skip this part; it is NOT needed!

Nested instances

Imagine that your Person DTO accepts more complex properties, e.g. an address;

NOTE: This example will only work if;

a) You are using the DTO inside a Laravel application

or

b) You have invoked the Bootstrap::boot() method, before using the given DTO (...once again this is not needed, if you are using this package inside a Laravel application)

In the above example, Laravel's Service Container attempts to find and create any concrete instances that are expected.

Furthermore, the default DTO abstraction (Aedart\DTO\DataTransferObject) will attempt to automatically populate that instance.

Interface bindings

If you prefer to use interfaces instead, then you need to bind those interfaces to concrete instances, before the DTOs / service container can handle and resolve them.

Outside Laravel Application

If you are outside a Laravel application, then you can bind interfaces to concrete instances, in the following way;

Inside Laravel Application

Inside your application's service provider (or perhaps a custom service provider), you can bind your DTO interfaces to concrete instances;

Example

Given that you have bound your interfaces to concrete instances, then the following is possible

Contribution

Have you found a defect ( bug or design flaw ), or do you wish improvements? In the following sections, you might find some useful information on how you can help this project. In any case, I thank you for taking the time to help me improve this project's deliverables and overall quality.

Bug Report

If you are convinced that you have found a bug, then at the very least you should create a new issue. In that given issue, you should as a minimum describe the following;

• Where is the defect located
• A good, short and precise description of the defect (Why is it a defect)
• How to replicate the defect
• (A possible solution for how to resolve the defect)

When time permits it, I will review your issue and take action upon it.

Fork, code and send pull-request

A good and well written bug report can help me a lot. Nevertheless, if you can or wish to resolve the defect by yourself, here is how you can do so;

• Fork this project
• Create a new local development branch for the given defect-fix
• Write your code / changes
• Create executable test-cases (prove that your changes are solid!)
• Commit and push your changes to your fork-repository
• Send a pull-request with your changes
• Drink a Beer - you earned it :)

As soon as I receive the pull-request (and have time for it), I will review your changes and merge them into this project. If not, I will inform you why I choose not to.

Acknowledgement

• Martin Fowler, for sharing his knowledge about DTOs and many other design patterns
• Taylor Otwell, for creating Laravel and especially the Service Container, that I'm using daily
• Jeffrey Way, for creating Laracasts - a great place to learn new things... And where I finally understood some of the principles of IoC!

Versioning

This package follows Semantic Versioning 2.0.0

License

BSD-3-Clause, Read the LICENSE file included in this package