Download the PHP package cascademedia/cartographer without Composer

Cartographer

Cartographer is a php library that provides the ability to transform data from one type into another type.

Installation

To install Cartographer, simply require the library by executing the following composer command.

Alternatively, you can clone/download this repository and install the package manually.

Basic Usage

There are three basic parts to the library: the mapper, mappings, and contexts.

• A context object exists to contain rules for an individual mapping use-case, for example: mapping user input to a data object or mapping an entity to a view model.
• A mapping object is effectively a rule that determines how data is mapped from one field to another within a given context.
• Finally, the mapper ties it all together and ensures that the proper mappings are executed from the source data to the destination.

Without further introduction, here is a simple example that maps from an input array to a User class. For more advanced usage, feel free to browse around the documentation.

Contexts

Contexts are classes that contain all of the rules used for an individual operation. When using the mapper, it is required to contain mapping rules within a context.

To create a context, create a class that implements and use to return a map containing all mapping rules desired.

References

References are classes used by the mapper to to retrieve or store field data in an object or array. The mapper currently supports array, object mutator, and object property references.

Reference classes are not typically used directly unless you are manually creating field mappings.

Array References

The class tells the mapper that you wish to access data contained within the top level of an array.

The method allows users to retrieve data from any given array.

The method allows users to put data into any given array. Note that this method returns a copy of the modified array and does not modify the original array passed into it.

Mutator References

The class tells the mapper that you wish to access data returned from a class' method call. By default, this reference will attempt to use getters and setters of the named field. For example, referencing a field named will call and respectively, but can be configured to call other methods if necessary.

Note that only public methods can be accessed. Accessing private and protected methods will result in a being thrown.

The method will call the configured getter method for the given object and return its result.

The method will call the configured setter method for the given object.

If the default getters and setters are not satisfactory, you can change the methods that are called via the reference's constructor.

Property References

The class tells the mapper that you wish to access data contained within a class' public property. Note that only public properties can be accessed. Accessing private and protected properties will result in a being thrown.

The method will return the data contained in the referenced object property.

The method will put data into the referenced object property.

Mappings

Mapping classes are the workhorse of the mapper library. They are the classes that map individual pieces of data using references to determine where the data comes from and where it goes.

Mapping

The class is the most straightforward of all mappings. It simply takes the source and maps it directly to the configured destination. When constructing the class, the destination reference comes first followed by the source reference.

Embedded Mapping

The class allows for mapping embedded data structures to the destination. When constructing the class, the source field comes first followed by a map describing how the embedded structure will be mapped to the destination.

Resolver Mapping

The class allows for the use of Value Resolvers to map data to a destination.

Value Resolvers

A value resolver is an object that will take the entire source object and return an individual value from it. Using a value resolver allows for arbitrary logic in order to map a value.

Callable Value Resolver

The library comes with a flexible class out-of-the-box, allowing value resolvers to be defined without the need to define resolver classes.

The Map Builder

To ease the creation of maps within a context, the library comes with a class that provides a simple, fluent interface to build a map. The is built to solve most use cases so that the user should rarely have to manually create mappings.

Defining default reference types

The class allows you to designate the default reference types using the and methods. These methods accept the constants , , and respectively. If any values other than the previously mentioned constants are used, an is thrown.

If the and methods are not called, then the reference type is assumed for both.

Adding Mappings

There are methods on the class that allows for the addition of pre-built mapping types, as well as the ability to add custom mappings.

The method simply creates a new Mapping using the determined reference types.

The method creates an Embedded Mapping using the determined reference types.

The method creates a Resolver Mapping using the determined reference types.

Finally, the method simply adds a custom user-defined mapping.

Building the Map

Once all mappings have been added into the , it's time to generate a that can be used within a context. The method generates a new for our uses.

Want to contribute?

If you would like to contribute to this library, you can do so in a couple of ways:

• Submit issues for bugs or functionality that would improve the project.
• Submit a pull request for new functionality.
• Update any documentation that appears to be lacking.

When submitting pull requests, please make sure functionality is covered by unit tests, and that all of the tests pass.

License

This library is MIT licensed, meaning it is free for anyone to use and modify.