PHP SDK for realtime synchronization with DSYNC
Switch branches/tags
Nothing to show
Clone or download
Latest commit fb08139 Dec 13, 2017
Permalink
Failed to load latest commit information.
examples Initial commit Dec 11, 2017
src Initial commit Dec 11, 2017
tests Initial commit Dec 11, 2017
.gitignore Initial commit Dec 11, 2017
LICENSE Initial commit Dec 11, 2017
README.md Fix typo Dec 13, 2017
build.xml Remove tabs Dec 11, 2017
composer.json Change composer type Dec 13, 2017
phpcs.xml Remove tabs Dec 11, 2017
phpunit.xml Remove tabs Dec 11, 2017

README.md

DSYNC PHP SDK

PHP SDK for realtime synchronization with DSYNC

Overview

The DSYNC PHP SDK is a quick start bundle for developers who are interested in connecting 3rd party systems with the DSYNC platform. By crafting an external connector based on the SDK, your system will be automatically able to exchange data in near real-time with vast array of different systems, APIs, and databases already available on the DSYNC platform.

Near real-time data exchange between DSYNC and 3rd party system uses the secured http protocol. The external connector you need to build is essentially a RESTful API able to receive and send http requests from and to the DSYNC platform only. Some systems may have an existing API which you can simply extend and bend to the DSYNC specification or you may need to build one from scratch.

You don’t have to be concerned with all the different APIs disparate systems may have – that’s DSYNC’s responsibility. All you need to build is the communication channel between your system and the DSYNC platform.

Authentication

DSYNC platform uses API keys for communication with 3rd party systems. You can create a new API key from within your DSYNC account by going into “My Account” section. Treat this key as a password. Anyone with the key can send/receive data on your behalf. As there is no expiration set for API keys, it is highly recommended to rotate the API key every so often to prevent unauthorised access.

The API key must be sent with every request you make to the DSYNC platform. Your connector must be able to store this key and send it in ‘Auth-Token’ header along with the request data. If you fail to send valid API key the DSYNC platform responds with 401 Unauthorized. The DSYNC PHP SDK will add the headers for you when you set the authorization token on the request.

Glossary

Data Layout

Schema in JSON format which defines one or more endpoints and all their respective fields. Generated by you in 3rd party system and sent to DSYNC.

For DSYNC to build and display a new system correctly on the canvas, the data layout which your connector generates must define at least one entity and the entity must have at least one field (eg. Product entity with SKU field).

Endpoint/Entity

A single resource/object inside the 3rd party system. (eg. Product).

Field

An attribute of an entity (eg. SKU)

API Key

(aka Auth Token) Password used to authenticate http requests between 3rd party system and the DSYNC platform

Entity Token

(aka Endpoint Token) Unique identifier of an endpoint generated by 3rd party system and sent to DSYNC in data layout. System scope – must be unique.

Treekey

Uniquely identifies position of a single field inside an entity schema. Uses object dot notation. Entity scope – must be unique.

Getting Started

  • Create a DSYNC account (https://www.dsync.com/pricing)
  • Create an auth token in the created account to use with the SDK
  • Create consumable endpoint to generate datalayout for the DSYNC application (see below)
  • Install a DIY system on your DSYNC dashboard

Full account setup instructions can be found at the Developer Portal (https://dsyncsdk.docs.apiary.io/reference/diy-connector)

API Documentation

Full API documentation can be found at the Developer Portal (https://dsyncsdk.docs.apiary.io/reference/source)

Installation

Install this package with composer:

composer require dsync/php-sdk

Requests

Create a request using the RealtimeRequest object. You can add authentication and endpoint token (that was set in the datalayout) along with the data before making the request.

Example realtime "Create" request


use Dsync\PhpSdk\Endpoint\RealtimeRequest;
use Dsync\PhpSdk\Exception\RealtimeRequestException;

$data = ['foo' => 'bar'];

// create a new realtime request object with your authorization token, endpoint token and data
$request = new RealtimeRequest('yourAuthToken', 'yourEndpointToken', $data);

try {
    // send a create request
    $result = $request->create();
} catch (RealtimeRequestException $e) {
    // do something if there is an exception
}

Example realtime "Update" request


use Dsync\PhpSdk\Endpoint\RealtimeRequest;
use Dsync\PhpSdk\Exception\RealtimeRequestException;

$data = ['foo' => 'foo'];

// create a new realtime request object
$request = new RealtimeRequest();

// set your authorization token, endpoint token and data on the request
$request
    ->setAuthToken('yourAuthToken')
    ->setEntityToken('yourEndpointToken')
    ->setData($data);

try {
    // send an update request
    $result = $request->update();
} catch (RealtimeRequestException $e) {
    // do something if there is an exception
}

Example realtime "Delete" request

The 'Delete' request requires the primary key (setEntityId) that was defined in the datalayout as as this method does not send a body.


use Dsync\PhpSdk\Endpoint\RealtimeRequest;
use Dsync\PhpSdk\Exception\RealtimeRequestException;

// create a new realtime request object with your authorization token and endpoint token
$request = new RealtimeRequest('yourAuthToken', 'yourEndpointToken');

// set your primary key for the entity you wish to delete as defined by the datalayout
$request->setEntityId('primaryKeyAsDefinedInDatalayout');

try {
    // send a delete request
    $result = $request->delete();
} catch (RealtimeRequestException $e) {
    // do something if there is an exception
}

Responses

All realtime methods will throw a RealtimeRequestException on error or return an array of data if successful.

Datalayout Utils

The PHP SDK comes with some utils to generate the layout and tokens for each endpoint. The DSYNC application must be able to consume your generated datalayout. For further details please see the Developers Portal (https://dsyncsdk.docs.apiary.io/#reference/destination/data-layout/get-data-layout)

Example of generating a datalayout array

Build the fields first and add them to the endpoint objects. Add the endpoint objects to the datalayout object before running the 'generate' method.

use Dsync\PhpSdk\Utils\Generator\Datalayout;
use Dsync\PhpSdk\Utils\Generator\Endpoint;
use Dsync\PhpSdk\Utils\Generator\Field;

// create a new field object
$field = new Field();

// set field information
// a list of field type constants can be found in the Dsync\PhpSdk\Utils\Generator\Field class
$field
    ->setPrimaryKey(true)
    ->setRequired(true)
    ->setTreekey('product.sku')
    ->setDescription('A product SKU')
    ->setName('sku')
    ->setType(Field::TYPE_TEXT);

// create a new endpoint object
$endpoint = new Endpoint();

// set endpoint information and add all fields using the addField method
$endpoint
    ->setEntityName('product')
    ->setTreekey('product')
    ->setEntityToken('source-1-product-b5503a0ae5f3bc01b6a2da68afd33305')
    ->setEndpointUrl('/entity/product')
    ->addField($field);

// finally create a new datalayout object
$datalayout = new Datalayout();

// add all endpoints using the addEndpoint method and call the generate method 
// to create the datalayout array
$datalayoutArray = $datalayout
    ->addEndpoint($endpoint)
    ->generate();

If using Symfony or something similar add the generated array to the response:

$response = new JsonResponse();

$responseArray = [
    'status' => 200,
    'message' => 'OK',
    'detail' => '',
    'data' => $datalayoutArray
];

$response->setData($responseArray);

return $response;

Example of generating an entity token

use Dsync\PhpSdk\Utils\Generator\Endpoint;
use Dsync\PhpSdk\Utils\Generator\EntityToken;

$entityTokenClass = new EntityToken();

// generate the entity token using an endpoint name as reference
$entityToken = $entityTokenClass->generateEntityToken('product');

$endpoint = new Endpoint();

// set the entity token on the endpoint object
$endpoint
    ->setEntityName('product')
    ->setTreekey('product')
    ->setEntityToken($entityToken)
    ->setEndpointUrl('/entity/product')
    ->addField($field);

// save $entityToken to make requests at a later time

Running developer coding standards and tests

Install packages with composer:

$ composer install

Install Ant (http://ant.apache.org/):

$ apt-get install ant

Run Ant:

$ ant