Mapper Utilities

We've included a mapper utility that helps map your data structures with ours. 

We created the mapper classes below because our classes get quite large and writing assignment expressions all the time gets a little tiresome. If you are using our APIs in multiple places you may find defining mapper objects saves you time in the long-term.

PropertyMap Class

Evance\Utils\PropertyMap

The PropertyMap class is capable of mapping properties within an associative array, a stdClass, classes with public properties or classes with get and set methods. You'll find that we use the terms left and right almost like visualising an assignment expression:

$leftObject->leftProperty = $rightObject->rightProperty;

However, assignment can be done either from left to right, or right to left.

Although a PropertyMap can be used independently, it would be almost pointless - it's designed to be used with an ObjectMap.

ObjectMap Class

Evance\Utils\ObjectMap

The ObjectMap is designed to map multiple properties of two different objects. This allows you to do things like mapping an Evance Service Class to an associative array, or a stdClass to any other kind of class assuming it is compatible with the PropertyMap capabilities (above).

Once again we use the terms left and right:

$leftObject = $rightObject;

Once again, assignment can be done from left to right, or right to left.

Example

Let's imagine you have a MyCustomer class that looks something like the following. 

class MyCustomer
{
    // example of public properties
    public $firstName;
    public $lastName;
    public $emailAddress;

    // example of a private property with getter and setter methods
    private $companyName;


    public function __construct(int $id)
    {
        // obtains data from a database
    }

    public function save()
    {
        // saves data back to the database
    }

    public function getCompanyName()
    {
        return $this->companyName;
    }

    public function setCompanyName($companyName)
    {
        $this->companyName = $companyName;
        return $this;
    }
}

If you wanted to map the fields of the Evance Contact API Service Class to your own MyCustomer class, you could create a new class. Let's call it a CustomerApiMap. You only need need to map the fields that are relevant to you. 

use Evance\Utils\ObjectMap;
use Evance\Utils\PropertyMap;
use Evance\Service\Contact as EvContact;

class CustomerApiMap extends ObjectMap
{
    public function __construct(MyCustomer &$myCustomer, EvContact &$evContact)
    {
        parent::__construct();
        $this->add(new PropertyMap($myCustomer, 'firstName', $evContact, 'firstname'));
        $this->add(new PropertyMap($myCustomer, 'lastName', $evContact, 'lastname'));
        $this->add(new PropertyMap($myCustomer, 'companyName', $evContact, 'company'));
        $this->add(new PropertyMap($myCustomer, 'emailAddress', $evContact, 'email'));
    }
}

We can now use this map whenever an interaction with the API needs to be reflected in your own data set, or vice versa. In the example below we are saving contact information from or local database to Evance as a new "user" (the default contact type).

$client = new Evance\ApiClient();
$client->loadAuthConfig('/path/to/api-credentials.json');
$token = $client->fetchAccessTokenWithJwt();

// get a Customer from our local database
$myCustomer = new MyCustomer(1);

// prepare an Evance Contact object
$evContact = new EvContact($client);

// create a new map instance relating myCustomer with evContact
$map = new CustomerApiMap($myCustomer, $evContact);

// assign values from myContact to evContact
$map->assignLeftToRight();

// save the contact data to Evance
$evContact->save();

You can find these classes on GitHub. They're available under MIT licence so feel free to use them.