Download the PHP package articus/data-transfer without Composer

Data Transfer

This library provides a "validating hydrator", a service that patches destination data with source data only if destination data remains valid after that. Source and destination can be anything - scalars, arrays, objects... So either you want to make a partial update of ORM entity with parsed JSON from HTTP-request or produce a plain DTO from this entity to send in AMQP-message this library can help you to do that in a neat convenient way.

How it works?

Let's make few definitions:

• typed data - some complex, application-specific, rigidly structured data like object or array of objects. For example, DTO's or ORM entities.
• untyped data - the opposite of typed data - some simple, general-purpose, amorphous data like scalar or array of scalars or stdClass instance. For example, result of json_decode or yaml_parse.
• extract - an algorithm to convert typed data to untyped data
• merge - an algorithm to patch one piece of untyped data with another piece of untyped data
• validate - an algorithm to check that untyped data is correct according some rules
• hydrate - an algorithm to patch typed data with untyped data

So if we have two pieces of typed data - A and B - this library does a rather simple thing to transfer A to B: it merges pieces of untyped data extracted from A and B, validates the result and hydrates B with untyped data extracted from A if validation is successful.

Why?

Personally I just needed something to easily update DTOs and Doctrine entities from untrusted sources (like request parsed body, request headers, request query parameters and etc). Something like request body converter from FOSRestBundle and JMS Serializer, but more flexible. The initial prototype was extremely useful for building APIs and after using it in several production projects I finally decided to make it a separate library. Hopefully, it will be useful for someone else.

How to install?

Just add "articus/data-transfer" to your composer.json and check packages suggested by the library for extra dependencies of optional components you may want to use.

How to use?

Library provides a single service Articus\DataTransfer\Service that allows transferring data in various ways. So first of all you need to register it in your PSR-11 container. You can use any PSR-11 implementation you like, but integration with Laminas Service Manager has slightly more features (to be precise - utilization of plugin managers and supports for Laminas validators). Here are two sample configurations:

• for Laminas Service Manager:

• for Symfony Dependency Injection:

That is the only requirement to use Articus\DataTransfer\Service::transfer method that provides the most explicit and fine-grained control over data transfer.

If you provide some additional metadata for classes that you would like to use with data transfer service several more convenient methods will be available:

• Articus\DataTransfer\Service::transferTypedData
• Articus\DataTransfer\Service::transferToTypedData
• Articus\DataTransfer\Service::transferFromTypedData
• Articus\DataTransfer\Service::extractFromTypedData

Currently, the default way to declare metadata shown in code examples across this documentation is via Doctrine Annotations. If your project uses PHP 8+ you may declare metadata via attributes instead (just switch from Articus\DataTransfer\MetadataProvider\Annotation to Articus\DataTransfer\MetadataProvider\PhpAttribute). And you can create your own implementation for Articus\DataTransfer\ClassMetadataProviderInterface if you want to get metadata from another source.

Metadata consists of two parts:

• strategy - Articus\DataTransfer\Strategy\StrategyInterface implementation that knows how extract, merge and hydrate class objects
• validators - one or more Articus\DataTransfer\Validator\ValidatorInterface implementations that know how to validate untyped data from class objects

One class may have several subsets of metadata distinguished by name, default subset name is empty string:

Build-in strategies and validators

Pretty often data transfer of object simply means data transfer of its properties. Library provides a convenient way to handle this scenario. If you add some special metadata for class properties then Articus\DataTransfer\Strategy\FieldData will be used as class strategy and Articus\DataTransfer\Validator\FieldData will be added to class validator list at highest priority:

Same as for class metadata there may be several subsets for property metadata and Doctrine Annotations is the default way to declare property metadata. If your project uses PHP 8+ you may declare property metadata via attributes instead (just switch from Articus\DataTransfer\MetadataProvider\Annotation to Articus\DataTransfer\MetadataProvider\PhpAttribute). And you can create your own implementation for Articus\DataTransfer\FieldMetadataProviderInterface if you want to use another metadata source.

Enjoy!

I really hope that this library will be useful for someone except me. It is used for production purposes but it lacks lots of refinement, especially in terms of tests and documentation.

If you have any suggestions, advices, questions or fixes feel free to submit issue or pull request.