PHP SDK for realtime synchronization with DSYNC
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.
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.
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.
- 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)
Full API documentation can be found at the Developer Portal (https://dsyncsdk.docs.apiary.io/reference/source)
Install this package with composer:
composer require dsync/php-sdk
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.
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
}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
}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
}All realtime methods will throw a RealtimeRequestException on error or return an array of data if successful.
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)
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;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 timeInstall packages with composer:
$ composer install
Install Ant (http://ant.apache.org/):
$ apt-get install ant
Run Ant:
$ ant