Download the PHP package kassko/data-mapper without Composer

data-mapper

A php mapper very tunable, cross-orm and cross-DBMS

• Objects do not extends a base entity class
• Map nested objects
• Support relationship between all types of sources (relational databases, non relational, caches ...)
• Lazy loading
• Supports dynamic configuration with expression language
• Various mapping configuration format
• Can chain some fallbacks sources while a source is unavailable or instable

Installation

Note that:

• version contains 4 numbers
• the second version number is used when compatibility is broken
• the third for new feature
• the fourth for hotfix
• the first for new API or to go from pre-release to release (from 0 to 1)

Using a version in 0.12 is recommended. Versions in 0.13 are no longer maintained.

Example of good requirement:

Basic usage

• Installation: precisions
• Accessing datas
  • Inline data sources
• Hydrating your object
  • Hydrating your object using inline data sources
  • Hydrating your object using a data source store
  • Working with sources and dependency injection
  • Example with a relation with a Doctrine source
  • Source annotation details
• Component configuration reference
• Mapping configuration reference
  • Config config
  • CustomHydrator config
  • DataSource config
  • DataSourcesStore config
  • ExcludeImplicitSource config
  • Field config
  • Getter config
  • Id config
  • IdCompositePart config
  • Listeners config
  • Method config
  • Object config
  • ObjectListeners config - DEPRECATED - SEE Listeners config
  • PostExtract config - DEPRECATED - SEE Listeners config
  • PostHydrate config - DEPRECATED - SEE Listeners config
  • PreExtract config - DEPRECATED - SEE Listeners config
  • PreHydrate config - DEPRECATED - SEE Listeners config
  • Provider config - DEPRECATED - SEE DataSource config
  • ProvidersStore config - DEPRECATED - SEE DataSourcesStore config
  • RefImplicitSource config
  • RefSource config
  • Setter config
  • ToExclude config
  • ToInclude config
  • Transient config
  • ValueObject config - DEPRECATED - SEE Config config
  • Version config

Run tests

Ensures phpunit is installed phpunit

Installation: precisions

If you use annotations, register the autoloader:

And run the environment:

Accessing datas

Data-mapper style

Doctrine style

With data-mapper, you only need to call a getter, the access logic is in a configuration.

The configuration is either in the object php file or in a separated file. If it's in the object file, the configuration is in annotations or a method returns it in a php array or in a yaml string. If it's in a separated file, the configuration is in a php or a yaml file.

For simplicity, the usage is documented with annotations format. But in this documentation, you can find reference guide for the others formats.

Hydrating your object

Hydrating your object using inline data sources

Hydrating your object using a data source store

A DataSource store is usefull

If you prefer to group your sources in one place:

Or if you have a source which hydrate several properties:

Note that you don't have to expose the setters. Expose them only if you have specific logic to write. I advise you not to make "public" these setters since the properties they wrapp are loaded (and so managed) with a data source.

Working with sources and dependency injection

CarRepository has some dependencies too (the entity manager), it is instantiated with a resolver class-resolver. Reminder: you can see more details here.

Run environment and register dependencies:

You can send an object which implements \ArrayAccess:

Or send an object which have "get" and "has" methods:

And you specify your dependency id like below:

Source annotation details

• id. An arbitrary id for the source. Optional but necessary if you need to mentionned the source in another annotation.
• class. The class of the source that return datas. If the source has some dependencies (above PersonDataSource has a dependency $connection), its instanciation can be performed by a resolver named class-resolver. See more details here.
• method. The name of the method that return datas.
• args. Arguments of the method that return datas. You can send a raw value, a field value with the prefix # (ex: #id), an expression and more ... See more details here
• supplySeveralFields. Whether the source returns the data directly or put them in a key of an array and return the array. If the source supply only one field, it can return directly the data, these data will be bound to the good property. Else the source should return an array with as keys as property to supply. The key is named like the property or a mapping is done in the annotation Field.

Data-mapper is not an ORM so it cannot generate for you some sql statement. But it can wrapp the use of an ORM like Doctrine ORM so that you can take advantage of the two. It also can help you to make relations between different DBMS.

Example with a relation with a Doctrine source

Features: details

• Basic usage
• Use the Result builder
• Enforce type of fields
• Apply converters before hydration or extraction
  • Converter
  • Date converter
• Add callbacks before or after hydration process
• Customize getters and setters
• Hydrate nested objects
• Configure a php object hydrator instead of using a mapping configuration
• Work with object complex to create like service
• Work with other mapping configuration format
  • Outer mapping configuration format
  • Inner mapping configuration format
• Improve persistance ignorance
• Choose a mapping configuration at runtime
• Bind a mapping configuration to a property especially
• Bind a source to a property or a set of properties / hydrate object from multi-sources, multi-orm
  • Data source
  • Method arguments
  • Lazy loading
  • Source store
  • Fallback source
  • Processor
  • Depends
• Work with relations
• How to have DataMapper/ResultBuilder ignorance in the client code
• Use expression language
  • Basic usage of expression language
  • Add a function provider
• Object listener
• Add a custom mapping configuration format
• Inherit mapping configuration

=======================================================================================================

Basic usage

Given an object:

Use the ResultBuilder:

The result builder allows you to hydrate all a collection from a result that contains several records. It also allows you to get only one result even if the result contains several records.

The code above will display:

Inversely, you can extract values of an object or of an object collection:

Above, we use the default hydrator. But you often need to customize hydration because column names are different of properties name and for many other reasons.

To customize the hydration you should provide a mapping configuration. Severals formats are available but in this documentation we choose to use the annotation format (more details about all mapping configuration format are available here).

Use the result builder

You can find below all the ways to get results with the ResultBuilder:

Enforce type of fields

This section will be written later.

Apply converters before hydration or extraction

Converter

readDateConverter contains the format of the string to transform into Date object. Internally, DataMapper uses the Php function DateTime::createFromFormat() to create a Date object from a raw string.

writeDateConverter contains the string format in which you want to serialize your Date object. Internally, DataMapper uses the Php function DateTime::createFromFormat() to serialise the Date object in a string.

Given this code:

Your output will be:

If the created_date had a bad format, an exception would have been thrown. For example, the format given above in the read date converter is 'Y-m-d H:i:s', so a create_date like '2014 09 14 12h36m52s' is not correct.

Date converter

This section will be written later.

Add callbacks before or after hydration process

This section will be written later.

Customize getters and setters

DataMapper automatically recognize getter (or isser or haser) and setter of a field.

To retrieve the corresponding getter, DataMapper look in order at:

• a getter
• an isser
• a haser

You also can specify corresponding getters/setters:

Hydrate nested objects

This section will be written later.

Configure a php object hydrator instead of using a mapping configuration

This section will be written later.

Work with object complex to create, like service

This section will be written later.

Work with other mapping configuration format

This section will be written later.

Outer mapping configuration format

This section will be written later.

Inner mapping configuration format

This section will be written later.

Improve persistance ignorance

This section will be written later.

Choose a mapping configuration at runtime

You can use the same model with various mapping configuration but you must work with one of the outer mapping configuration and not with mapping embedded in the object. So 'yaml_file' or 'php_file' are correct mapping format but 'annotations', 'inner_php' or 'inner_yaml' are bad format.

A english data source with the mapping in yaml:

A french data source with the mapping in yaml:

And imagine we've got a spanish data source with the mapping in a php format.

Bind a mapping configuration to a property especially

Note that you can have value objects which contains value objects and so on. And each value object can use it's own mapping configuration format.

Bind a source to a property or a set of properties / hydrate object from multi-sources, multi-orm

Data source

Method arguments

This section will be written later.

Lazy loading

Below, we load properties "bestShop" and "keyboard" only when we use it.

Source store

Given this code:

We can remove the duplication:

Fallback source

Here, sourceB replace sourceA if its not stable:

Or:

Bad return values could be: "null", "false", "emptyString" or "emptyArray".

Processor

Or:

Depends

depends contains sources of which depends an other source. It's usefull when you need to ensures that a property is already available in a zone.

This section will be completed later.

Work with relations

This section will be written later.

How to have DataMapper/ResultBuilder ignorance in the client code

This section will be written later.

Use expression language

This section will be written later.

Basic usage of expression language

This section will be written later.

Add a function provider

This section will be written later.

Object listener

This section will be written later.

Add a custom mapping configuration format

This section will be written later.

Inherit mapping configuration

This section will be written later.

Component configuration reference

(1) availables types are annotations, yaml_file, php_file, inner_php, inner_yaml. And maybe others if you add some custom mapping loaders.

Mapping configuration reference

Config config

Annotation format:

Yaml format:

Php format:

CustomHydrator config

Annotation format:

Yaml format:

Php format:

The methods prototype:

DataSource config

Annotation format:

Yaml format:

Php format:

To know more about the "Method config" usage, please see its dedicated documentation "Method config".

DataSourcesStore config

Annotation format:

Yaml format:

Php format:

To know more about the "Method config" usage, please see its dedicated documentation "Method config".

ExcludeImplicitSource config

Annotation format:

Yaml format:

Php format:

Field config

Annotation format:

Yaml format:

Php format:

Getter config

Annotation format:

Yaml format:

Php format:

Id config

Annotation format:

Yaml format:

Php format:

IdCompositePart config

Annotation format:

Yaml format:

Php format:

Listeners config

Annotation format:

Yaml format:

Php format:

Method config

Annotation format:

Yaml format:

Php format:

Object config

Annotation format:

Yaml format:

Php format:

ObjectListeners config - DEPRECATED - SEE Listeners Config

Annotation format:

Yaml format:

Php format:

PostExtract config - DEPRECATED - SEE Listeners Config

Deprecated. Use Listeners config instead.

Annotation format:

Yaml format:

Php format:

PostHydrate config - DEPRECATED - SEE Listeners Config

Deprecated. Use Listeners config instead.

Annotation format:

Yaml format:

Php format:

PreExtract config - DEPRECATED - SEE Listeners Config

Deprecated. Use Listeners config instead.

Annotation format:

Yaml format:

Php format:

PreHydrate config - DEPRECATED - SEE Listeners Config

Deprecated. Use Listeners config instead.

Annotation format:

Yaml format:

Php format:

Provider config - DEPRECATED - SEE DataSource Config

Deprecated. Use DataSource config instead. Configuration is the same as DataSource.

ProvidersStore config - DEPRECATED - SEE DataSourcesStore Config

Deprecated. Use DataSourcesStore config instead. Configuration is the same as DataSourceStore.

RefImplicitSource config

Annotation format:

Yaml format:

Php format:

RefSource config

Annotation format:

Yaml format:

Php format: php use Kassko\DataMapper\Annotation as DM;

class SomeClass { /**

• @DM\Setter(
• prefix="setterPrefix",
• name="setterName"
• ) */ protected $firstField; } yml fields: firstField: name: firstField setter: name: setterName yml

  Optional because it's the default settings for fieldExclusionPolicy.

  object:

  fieldExclusionPolicy: include_all

  excludedFields: [excludedField] fields: excludedField: name: excludedField anotherField: name: anotherField php use Kassko\DataMapper\Annotation as DM;

/**

• @DM\Object(fieldExclusionPolicy="exclude_all") */ class SomeClass { /**

  • @DM\Include */ protected $includedField;

  /**

  • @DM\Field */ protected $field; } yml fieldExclusionPolicy: exclude_all fieldsToInclude: [includedField] fields: includedField: name: includedField anotherField: name: anotherField php [ 'fieldExclusionPolicy' => 'exclude_all' 'fieldsToInclude' => [ 'includedField' ], 'fields' => [ 'includedField' => [ 'name' => 'includedField' ], 'anotherField' => [ 'name' => 'anotherField' ], ] ]; php use Kassko\DataMapper\Annotation as DM;

class SomeClass { /**

• @DM\Transient */ protected $firstField;

  /**

• @var string */ protected $secondField; } yml transient: [firstField] fields: [firstField] php [ 'transient' => ['firstField'], 'fields' => [ 'firstField' => [ 'name' => 'firstFieldName' ] ] ]; php use Kassko\DataMapper\Annotation as DM;

class ValueObject { /**

• @DM\Config(
• class="\ValueObjectClass",
• mappingResourceName="valueObjectResourceName",
• mappingResourcePath="valueObjectResourcePath",
• mappingResourceType="valueObjectResourceType"
• ) */ protected $firstField; } yml fields: firstField: name: firstField valueObjects: firstField: class: "\\ValueObjectClass" mappingResourceName: valueObjectResourceName mappingResourcePath: valueObjectResourcePath mappingResourceType: valueObjectResourceType php [ 'fields' => [ 'firstField' => [ 'name' => 'firstField', ] ], 'valueObjects' => [ 'firstField' => [ 'class' => '\ValueObjectClass', 'mappingResourceName' => 'valueObjectResourceName', 'mappingResourcePath' => 'valueObjectResourcePath', 'mappingResourceType' => 'valueObjectResourceType' ] ] ]; php use Kassko\DataMapper\Annotation as DM;

class SomeClass { /**

• @DM\Version */ protected $firstField; } yml version: firstField fields: [firstField] php [ 'version' => 'firstField', 'fields' => ['firstField'] ];

========================================

• Result builder in details
• Map some property names to keys of your raw datas
• Convert some values before hydration or before extraction
• Use a data source for a property
• Lazy load some properties
• Use a data source for a set of properties
• Hydrate nested object or nested collections
• Use fallback data sources
• Use local config
• Select the fields to map
• Getters, isser, hasser and more get methods
• Choose or change an object mapping configurations at runtime
• Choose your mapping configuration format
• Configuration reference documentation
• Inner Yaml mapping reference documentation.
• Yaml mapping reference documentation.
• Inner php mapping reference documentation.
• Php mapping reference documentation.