Download the PHP package opportus/object-mapper without Composer

On this page you can find all versions of the php package opportus/object-mapper. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of opportus/object-mapper

Informations about the package object-mapper

Object Mapper

License Latest Stable Version Latest Unstable Version Build Codacy Badge Codacy Badge

Index

Meta

This document is a guide mainly walking you through the setup, concepts, and use cases of this solution.

API documentation is bound to code and complies to PHPDoc standards...

Secondary sections are collapsed in order to not overflow the first reading.

Introduction

Use this solution for mapping generically data from source to target object via extensible strategies and controls.

Delegate responsibility of all of your data mapping to a generic - extensible - optimized - tested mapping system.

Leverage that system to:

This project aims to provide a standard core system to higher level systems such as:

If you need to map from/to array data structure, simply cast it to/from object stdClass.

Roadmap

To develop this solution faster, contributions are welcome...

v1.1.0

Integrations

Setup

Step 1 - Installation

Open a command console, enter your project directory and execute:

Step 2 - Initialization

This library contains 4 services. 3 of them require a single dependency which is another lower level service among those 4:

In order for the object mapper to get properly initialized, each of its services must be instantiated such as above.

By design, this solution does not provide "helpers" for the instantiation of its own services which is much better handled the way you're already instantiating your own services, with a DIC system or whatever.

Mapping

Overview

In order to transfer data from a source object to a target object, the ObjectMapper iterates through each Route that it gets from a Map, assigning the value of the current route's source point to this route's target point.

Optionally, on the route, check points can be defined in order to control the value from the source point before it reaches the target point.

A route is defined by and composed of its source point, its target point, and its check points.

A source point can be either:

A target point can be either:

A check point can be any implementation of CheckPointInterface.

These routes can be defined PathFinderInterface strategy implementation and/or manually via:

Automatic Mapping

Remember that PathFinderInterface implementations such as those covered next in this section can get combined.

Static Path Finder

A basic example of how to automatically map User's data to UserDto and vice-versa:

Calling the ObjectMapper::map() method passing no $map argument makes the method build then use a Map composed of the default StaticPathFinder strategy.

The default StaticPathFinder strategy determines the appropriate point of the source class to connect to each point of the target class. Doing so, it defines a route to follow by the object mapper.

For the default StaticPathFinder, a reference target point can be:

The corresponding source point can be:

Static Source To Dynamic Target Path Finder

Click for details A basic example of how to automatically map `User`'s data to `DynamicUserDto`: The default `StaticSourceToDynamicTargetPathFinder` strategy determines the appropriate point of the *target* **object** (*dynamic point*) to connect to each point of the *source* **class** (*static point*). For the default [`StaticSourceToDynamicTargetPathFinder`](https://github.com/opportus/object-mapper/blob/master/src/PathFinder/StaticSourceToDynamicTargetPathFinder.php), a reference *source point* can be: - A public property ([`PropertyStaticSourcePoint`](https://github.com/opportus/object-mapper/blob/master/src/Point/PropertyStaticSourcePoint.php)) - A public getter requiring no argument ([`MethodStaticSourcePoint`](https://github.com/opportus/object-mapper/blob/master/src/Point/MethodStaticSourcePoint.php)) The corresponding *target point* can be: - A statically undefined (not existing in class) property having for name the same as the property *source point* or `lcfirst(substr($getterSourcePoint, 3))` ([`PropertyDynamicTargetPoint`](https://github.com/opportus/object-mapper/blob/master/src/Point/PropertyDynamicTargetPoint.php))

Dynamic Source To Static Target Path Finder

Click for details A basic example of how to automatically map `DynamicUserDto`'s data to `User`: The default `DynamicSourceToStaticTargetPathFinder` strategy determines the appropriate point of the *source* **object** (*dynamic point*) to connect to each point of the *target* **class** (*static point*). For the default [`StaticSourceToDynamicTargetPathFinder`](https://github.com/opportus/object-mapper/blob/master/src/PathFinder/DynamicSourceToStaticTargetPathFinder.php), a reference *target point* can be: - A public property ([`PropertyStaticTargetPoint`](https://github.com/opportus/object-mapper/blob/master/src/Point/PropertyStaticTargetPoint.php)) - A parameter of a public setter or constructor ([`MethodParameterStaticTargetPoint`](https://github.com/opportus/object-mapper/blob/master/src/Point/MethodParameterStaticTargetPoint.php)) The corresponding *source point* can be: - A statically undefined (not existing in class) but dynamically defined (existing in object) property having for name the same as the *target point* ([`PropertyDynamicSourcePoint`](https://github.com/opportus/object-mapper/blob/master/src/Point/PropertyDynamicSourcePoint.php))

Custom Path Finder

The default path finders presented above implement each a specific mapping logic. In order for those to generically map differently typed objects, they have to follow a certain convention de facto established by these path finders. You can map generically differently typed objects only accordingly to the path finders the map is composed of.

If the default path finders do not suit your needs, you still can genericize and encapsulate your domain's mapping logic as subtype(s) of PathFinderInterface. Doing so effectively, you leverage Object Mapper to decouple these objects from your mapping logic... Indeed, when the mapped objects change, the mapping doesn't.

For best example of how to implement PathFinderInterface, refer to the default StaticPathFinder, StaticSourceToDynamicTargetPathFinder, and DynamicSourceToStaticTargetPathFinder implementations.

Example

Manual Mapping

If in your context, such as walked through in the previous "automatic mapping" section, a mapping strategy is impossible, you can manually map the source to the target.

There are multiple ways to define manually the mapping such as introduced in the 2 next sub-sections:

Via Map Builder API

Click for details The [`MapBuilder`](https://github.com/opportus/object-mapper/blob/master/src/Map/MapBuilder.php) is an immutable service which implement a fluent interface. A basic example of how to manually map `User`'s data to `ContributorDto` and vice-versa with the `MapBuilder`:

Via Map Definition Preloading

Click for details [Via the map builder API](#via-map-builder-api) presented above, we define the *map* (adding to it *routes*) *on the go*. There is another way to define the *map*, *preloading* its definition. While this library is designed with *map definition preloading* in mind, it does not provide a way to effectively *preload a map definition* which could be: - Any type of file, commonly used for configuration (XML, YAML, JSON, etc...), defining statically a *map* to build at runtime - Any type of annotation in *source* and *target* classes, defining statically a *map* to build at runtime - Any type of PHP routine, defining dynamically a *map* to build at runtime - ... A *map* being not much more than a collection of *routes*, you can statically define it for example by defining its *routes* FQN this way: Then at runtime, in order to create *routes* to compose a *map* of, you can: - Parse your map configuration files, extract from them *route* definitions - Parse your *source* and *target* annotations, extract from them *route* definitions - Implement any sort of map generator logic outputing *route* definitions Then, based on their definitions, build these *routes* with the initial instance of the [`MapBuilder`](https://github.com/opportus/object-mapper/blob/master/src/Map/MapBuilderInterface.php) which will keep and inject them into its built *maps* which in turn might return these *routes* to the *object mapper* depending on the source and target being mapped. Because an *object mapper* has a wide range of different use case contexts, this solution is designed as a minimalist, flexible, and extensible core in order to get integrated, adapted, and extended seamlessly into any of these contexts. Therefore, this solution delegates *map definition preloading* to the integrating higher level system which can make use contextually of its own DIC, configuration, and cache systems required for achieving *map definition preloading*. [opportus/object-mapper-bundle](https://github.com/opportus/ObjectMapperBundle) is one system integrating this library (into Symfony 4 application context). You can refer to it for concrete examples of how to implement *map definition preloading*.

Check Point

A check point, added to a route, allows you to control/transform the value from the source point before it reaches the target point.

You can add multiple check points to a route. In this case, these check points form a chain. The first check point controls the original value from the source point and returns the value (transformed or not) to the object mapper. Then, the object mapper passes the value to the next check point and so on... Until the last check point returns the final value to be assigned to the target point by the object mapper.

So it is important to keep in mind that each check point has a unique position (priority) on a route. The routed value goes through each of the check points from the lowest to the highest positioned ones such as represented below:

A simple example implementing CheckPointInterface, and PathFinderInterface, to form what we could call a presentation layer:

In this example, based on the Object Mapper's abilities, we code a whole application generic layer with no effort...

But what is a layer? Accordingly to Wikipedia:

An abstraction layer is a way of hiding the working details of a subsystem, allowing the separation of concerns to facilitate interoperability and platform independence.

The more the root system (say an application) has independent layers, the more it has data representations, the more it has to map data from one representation to another.

Think for example of the Clean Architecture:

Each of these layers' essence is to map data based on the logic they are composed of. This logic is what we can calle the flow of control over data.

Referring to our example... This flow of control is defined by the path finder. These controls are our check points. The ObjectMapper service is nothing but that concrete layered system. Such layered OOP system is an object mapper.

Recursion

A recursion implements CheckPointInterface. It is used to recursively map a source point to a target point.

This means:

An example of how to manually map a Post and its composite objects to its PostDto and its composite DTO objects:

Naturally, all that can get simplified with a higher level PathFinderInterface implementation defining these recursions automatically based on source and target point types. These types being hinted in source and target classes either with PHP or PHPDoc.

This library may feature such PathFinder in near future. Meanwhile, you still can implement yours, and maybe submit it to pull request... :)

All versions of object-mapper with dependencies

PHP Build Version
Package Version
Requires php Version >=7.4
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package opportus/object-mapper contains the following files

Loading the files please wait ....