xenolope/cartographer

A super-simple library to map JSON documents to objects, similar to Java's Jackson

Wednesday, January 28, 2015
by jonjomckay
Repository
3 Watchers
16 Stars
38 Installations

PHP
0 Dependents
0 Suggesters
0 Forks
0 Open issues
6 Versions
0 % Grown

The README.md

Cartographer

, _(*1)

Cartographer is a super-simple library for deserializing JSON into POPOs, similar to FasterXML's jackson-databind package for Java., _(*2)

Installation

The library can be installed with Composer, by including the following in your composer.json:, _(*3)

{
    "require": {
        "xenolope/cartographer": "~0.5"
    }
}

Usage

POPOs

Your POPOs must have a property and corresponding setter, with either the property having a @var ClassName docblock, or the setter having a type hint., _(*4)

Setters are called directly, and properties are never touched, even if they're declared public (though this might be added in a later version)., _(*5)

Simple values are converted to the types given in their @var docblocks (using settype()), objects are created based on the class specified in the @var docblocks, and arrays of objects are also created, and can be specified with the @var ClassName[] notation., _(*6)

class Contact
{

    /**
     * @var string
     */
    private $name;

    /**
     * @var Address
     */
    private $address;

    /**
     * Note, this property doesn't have a @var docblock, but the corresponding setter
     * below *does* have a type hint
     */
    private $secondaryAddress;

    /**
     * @var Note[]
     */
    private $notes;

    /**
     * @param string $name
     */
    public function setName($name)
    {
        $this->name = $name;
    }

    /**
     * @param Address $address
     */
    public function setAddress($address)
    {
        $this->address = $address;
    }

    /**
     * @param Address $secondaryAddress
     */
    public function setAddress(Address $secondaryAddress)
    {
        $this->secondaryAddress = $secondaryAddress;
    }

    /**
     * @param Note[] $notes
     */
    public function setNotes($notes)
    {
        $this->notes = $notes;
    }
}

Mapping

// Create a new instance of the Mapper
$mapper = new \Xenolope\Cartographer\Mapper();

// Map a JSON string to a POPO

// PHP 5.4
$object = $mapper->mapString(
    '{"name":"Liz Lemon","address":{"street":"168 Riverside Dr.","city":"New York"}}',
    'Vendor\Package\Entity\Contact'
);

// PHP >=5.5
$object = $mapper->mapString(
    '{"name":"Liz Lemon","address":{"street":"168 Riverside Dr.","city":"New York"}}',
    Contact::class
);

// Map an already decoded (to array) JSON document to a POPO

// This might happen automatically in your Request class, for example
$jsonDocument = json_decode(
    '{"name":"Liz Lemon","address":{"street":"168 Riverside Dr.","city":"New York"}}',
    true
);

// PHP 5.4
$object = $mapper->map($jsonDocument, 'Vendor\Package\Entity\Contact');

// PHP >= 5.5
$object = $mapper->map(
    '{"name":"Liz Lemon","address":{"street":"168 Riverside Dr.","city":"New York"}}',
    Contact::class
);