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.

Construct
$leftObject Accepts one of the following:

  • an associative array
  • a stdClass
  • Any class with public properties
  • Any class with get and set methods.
$leftProperty

The name of the property represented as a string. 

If you are using get and set methods for private properties, we assume your methods look something like getTitle() and setTitle($value). In this case simply provide 'title' as the property.

$rightObject Accepts one of the following: 

  • an associative array
  • a stdClass
  • Any class with public properties
  • Any class with get and set methods.
$rightProperty

The name of the property represented as a string. 

If you are using get and set methods for private properties, we assume your methods look something like getTitle() and setTitle($value). In this case simply provide 'title' as the property.


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.

Methods
add(PropertyMap $map) Accepts a PropertyMap which defines the objects and properties to map together.
assignLeftToRight() Assign the property values from the left object to those in the right object.
assignRightToLeft() Assign the property values from the right object to those in the left object. 

 

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.