README

Mapster

A lightweight PHP data mapping library. Easily converts json_decoded structures to actual classes.

License

MIT (http://opensource.org/licenses/MIT)

To do

Nothing! We're done, for now. If you find a bug or have an awesome idea, be sure to open an issue!

Requirements and limitations

PHP v5.3+
Mapped classes must have an empty constructor: __construct();
array is a reserved class name that maps to a regular array.

Installation

You can either download the code and include the Mapster/Mapster.php file, or if you're using Composer then simply add the following requirement to your composer.json file:

{
	"require": {
		"imevul/mapster": "dev-default"
	}
}

This will add the latest source as a dependency to your project and autoload it via the Composer autoload feature. If you want to make sure you have a stable release, you can specify the version number instead. For example:

{
	"require": {
		"imevul/mapster": ">=1.1.1"
	}
}

Check the Tags page for the latest version.

Usage

This library handles both manually specified maps, as well as "magic" maps from the decoded data. For example, the following data would be cast as a Square:

{
  "__class__": "Square",
  "width": 20,
  "height": 20
}

For manual maps, you can specify a map on this form:

$map = array(
  "__class__" => "Square",
  "squareField" => array(
    "__class__" => "Triangle",
    "triangleField" => array(
      "__class__" => "array",
      "0" => array(
        "__class__" => "Circle",
        "circleField" => 3
      )
    )
  )
)

This would map the following data:

{
  "squareField": {
    "triangleField": [
      {
        "circleField": 3
      }
    ]
  }
}

Onto this structure:

new Square {
  $squareField = new Triangle() {
    $triangleField = array(
      new Circle() {
        $circleField = 3;
      }
    )
  }
}

To use the mapper, simply include the library file and run:

$mapper = new Mapster();
$result = $mapper->map($data);

Where $data is the array/object structure you wish to map.

AutoMappers

Starting with version 1.1.0, Mapster now has support for so called AutoMappers.

AutoMappers are custom classes that try to map some data to one or more classes depending on the fields in the data. This is useful when you don't have direct control over how your data input is generated, for example with json_decoded DateTime objects. For an example on how to write your own AutoMapper, please see the included DateTime mapper, as well as the AutoMapper interface.

You can disable this feature using the config if you do not intend to use it.

Autoboxing

As of version 1.1.5, you can now use the optional PropertyType annotation to automatically convert the actual value into an object instance. Ex:

class Entity {
	/** @PropertyType("Square") */
	public $square;
}

This would cast the value to a square using square's constructor, like so:

$entity->square = new Square($entity->square);

What you use this for is up to you. It is enabled by default if doctrine/common is required anywhere in your project. You can still disable autoboxing from ever triggering by setting the $config['use_autoboxing'] = FALSE.

Finally

If you find any bugs or have an idea that you think fits in this project, feel free to open an issue and/or send a pull request.

Changelog

2013-06-27 - v1.1.5

Refactored tests and added PHPCS ruleset.
Added (optional) support for Doctrine/Common annotation based autoboxing.

2013-06-20 - v1.1.4

Fixed a bug regarding protected and private properties.
Refactored code and added more unit tests.

2013-06-20 - v1.1.3

Updated folder structure, according to psr-0 standard.
Added library autoloading via Composer.

2013-06-19 - v1.1.2

Changed folder structure to a more common form.

2013-06-19 - v1.1.1

Added Composer support.
Updated installation instructions.

2013-06-19 - v1.1.0

Added support for custom AutoMappers. DateTime mapper included.

2013-06-19 - v1.0.0

Initial release. Fully working mapping is done.

imevul / mapster

Maintainers

Details