Debug mode¶

SDK allows to activate debug mode. Its purpose is to log all requests, responses and headers.

The debugging may be enabled by defining DREAMCOMMERCE_DEBUG constant.

You can define the constant in your source code:

define('DREAMCOMMERCE_DEBUG', true);

Logging messages¶

SDK allows to log all messages to stream.

The log file may be set by defining DREAMCOMMERCE_LOG_FILE constant.

You can define the constant in your source code:

define('DREAMCOMMERCE_LOG_FILE', "php://stdout");

Messages can be passed to simple logger class using multiple priorities:

\DreamCommerce\Logger::debug("debug message");
\DreamCommerce\Logger::info("informational message");
\DreamCommerce\Logger::notice("notice message");
\DreamCommerce\Logger::warning("warning message");
\DreamCommerce\Logger::error("error message");
\DreamCommerce\Logger::critical("critical message");
\DreamCommerce\Logger::alert("alert message");
\DreamCommerce\Logger::emergency("emergency message");

Debug messages are filtered if debug mode is disabled.

Catching exceptions¶

A code example using exceptions handling:

try{
    $client = new \DreamCommerce\Client(
        'https://myshop.example.com', 'Application ID', 'Secret'
    );

    $client->setAccessToken('SHOP TOKEN');

    // fetch collection/object
    $product = new \DreamCommerce\Resource\Product($client);
    $list = $product->get();

    foreach($list as $item){
        //...
    }

} catch (\DreamCommerce\Exception\ClientException $ex) {
    // client error
    \DreamCommerce\Logger::error($ex);
} catch (\DreamCommerce\Exception\ResourceException $ex) {
    // resource error
    \DreamCommerce\Logger::error($ex);
}

Each exception lets to access an exception of lower layer, eg. HTTP response. Simply use standard exception’s method getPrevious on every exception.

try{

    // ...

} catch (\DreamCommerce\Exception\ClientException $ex) {
    \DreamCommerce\Logger::error(sprintf("Client error: %s", $ex->getMessage()));

    $prev = $ex->getPrevious();

    if($prev instanceof \DreamCommerce\Exception\HttpException){
        \DreamCommerce\Logger::error(sprintf("HTTP error: %s", $prev->getMessage()));

        if($prev->getCode() == \DreamCommerce\Exception\HttpException::QUOTA_EXCEEDED){
            \DreamCommerce\Logger::warning("Quota exceeded");
        }
    }

} catch (\DreamCommerce\Exception\ResourceException $ex) {
    \DreamCommerce\Logger::error(sprintf("Resource error: %s", $ex->getMessage()));
}

In order to directly access error message, it’s possible to use static method DreamCommerce\Client::getError.

try{

    // ...

} catch (\DreamCommerce\Exception\ClientException $ex) {
    \DreamCommerce\Logger::error(sprintf("Client error: %s", Client::getError($ex)));
} catch (\DreamCommerce\Exception\ResourceException $ex) {
    \DreamCommerce\Logger::error(sprintf("Resource error: %s", Client::getError($ex)));
}

Configuration¶

return array(
    /*
     * Application ID generated by AppStore
     */
    'appId' => '',

    /*
     * Secret generated by AppStore
     */
    'appSecret' => '',

    /*
     * AppStore Secret generated by AppStore
     */
    'appstoreSecret' => '',

    /*
     * Enable debug mode or not
     */
    'debug' => false,

    /*
     * Path to log file or empty to disable logging
     */
    'logFile' => "logs/application.log",


    /*
     * timezone of the application
     *
     * Value is passed to date_default_timezone_set function
     */
    'timezone' => 'Europe/Warsaw',

    'php' => array(
        /*
         * This determines whether errors should be printed to the screen as
         * part of the output or if they should be hidden from the user
         *
         * Value is passed to ini_set function
         */
        'display_errors' => 'off'
    )
);

Bootstrapping¶

// force utf-8 as primary encoding
if (PHP_VERSION_ID < 50600) {
    mb_internal_encoding('utf-8');
} else {
    ini_set('default_charset', 'utf-8');
}

// internal autoloader
spl_autoload_register(function($class){
    $class = str_replace('\\', '/', $class);
    require 'src/'.$class.'.php';
});

// composer autoloader - you can enable it on by uncommenting this line:
//require 'vendor/autoload.php';

// use config from previous example
$config = require __DIR__. '/Config.php';

// various PHP configuration values
date_default_timezone_set($config['timezone']);
ini_set('display_errors', $config['php']['display_errors']);

// check debug mode options
$debug = false;
if(isset($config['debug'])){
    if($config['debug']){
        $debug = true;
    }
}
// check environment variable
if(getenv('DREAMCOMMERCE_DEBUG')){
    $debug = true;
}
define("DREAMCOMMERCE_DEBUG", $debug);

// log errors to stdout by default
$logFile = "php://stdout";
if(isset($config['logFile'])){
    if($config['logFile']){
        $logFile = $config['logFile'];
    }else{
        $config['logFile'] = false;
    }
}
define("DREAMCOMMERCE_LOG_FILE", $logFile);

return $config;

REST GET¶

use DreamCommerce\Client;
use DreamCommerce\Exception\ClientException;
use DreamCommerce\Exception\ResourceException;

$config = require 'bootstrap.php';

try {
    // set custom retries count
    // it will throw HttpException if the limit is too low
    \DreamCommerce\Http::setRetryLimit(2);
    $client = new Client(
        'https://myshop.example.com', $config['appId'], $config['appSecret']
    );
    $client->setAccessToken('INSERT TOKEN HERE');

    $resource = new \DreamCommerce\Resource\Product($client);
    // or
    $resource = $client->products;

    // particular object, with ID=1
    $result = $resource->get(1);

    // list of objects
    $result = $resource->get();

    // list of objects (page 3) with filtering/limiting:
    $result = $resource->filters(array('translations.name' => array('=', 'laptop')))->page(3)->limit(10)->get();

    printf("Found: %d\n", $result->count);
    printf("Page: %d of %d\n", $result->page, $result->pages);
    printf("Iterating over products:\n");
    foreach ($result as $i) {
        printf("ID #%d\n", $i->product_id);
        // or - for your convenience:
        //printf("ID #%d\n", $i['product_id']);
    }
} catch (ClientException $ex) {
    \DreamCommerce\Logger::error("An error occurred during the Client initialization: ".Client::getError($ex));
} catch (ResourceException $ex) {
    \DreamCommerce\Logger::error("An error occurred during Resource access: ".Client::getError($ex));
}

REST POST¶

use DreamCommerce\Client;
use DreamCommerce\Exception\ClientException;
use DreamCommerce\Exception\ResourceException;

$config = require 'bootstrap.php';

try {
    // set custom retries count
    // it will throw HttpException if the limit is too low
    \DreamCommerce\Http::setRetryLimit(2);
    $client = new Client(
        'https://myshop.example.com', $config['appId'], $config['appSecret']
    );
    $client->setAccessToken('INSERT TOKEN HERE');

    $resource = new \DreamCommerce\Resource\Producer($client);
    // or
    $resource = $client->producers;

    $insertedId = $resource->post(array(
        'name' => 'Awesome Manufacturer!',
        'web' => 'http://example.org'
    ));

    // or:
    $data = new stdClass();
    $data->name = 'Awesome Manufacturer!';
    $data->web = 'http://example.org';
    $insertedId = $resource->post($data);


} catch (ClientException $ex) {
    \DreamCommerce\Logger::error("An error occurred during the Client initialization: ".Client::getError($ex));
} catch (ResourceException $ex) {
    \DreamCommerce\Logger::error("An error occurred during Resource access: ".Client::getError($ex));
}

REST PUT¶

use DreamCommerce\Client;
use DreamCommerce\Exception\ClientException;
use DreamCommerce\Exception\ResourceException;

$config = require 'bootstrap.php';

try {
    // set custom retries count
    // it will throw HttpException if the limit is too low
    \DreamCommerce\Http::setRetryLimit(2);
    $client = new Client(
        'https://myshop.example.com', $config['appId'], $config['appSecret']
    );
    $client->setAccessToken('INSERT TOKEN HERE');

    $resource = new \DreamCommerce\Resource\Producer($client);
    // or
    $resource = $client->producers;

    $insertedId = $resource->put(2, array(
        'name' => 'Awesome Manufacturer!'
    ));

    \DreamCommerce\Logger::info("Object modified");

} catch (ClientException $ex) {
    \DreamCommerce\Logger::error("An error occurred during the Client initialization: ".Client::getError($ex));
} catch (ResourceException $ex) {
    \DreamCommerce\Logger::error("An error occurred during Resource access: ".Client::getError($ex));
}

REST DELETE¶

use DreamCommerce\Client;
use DreamCommerce\Exception\ClientException;
use DreamCommerce\Exception\ResourceException;

$config = require 'bootstrap.php';

try {
    // set custom retries count
    // it will throw HttpException if the limit is too low
    \DreamCommerce\Http::setRetryLimit(2);
    $client = new Client(
        'https://myshop.example.com', $config['appId'], $config['appSecret']
    );
    $client->setAccessToken('INSERT TOKEN HERE');

    $resource = new \DreamCommerce\Resource\Producer($client);
    // or
    $resource = $client->producers;

    $result = $resource->delete(41);
    \DreamCommerce\Logger::info("An object was successfully deleted");

} catch (ClientException $ex) {
    \DreamCommerce\Logger::error("An error occurred during the Client initialization: ".Client::getError($ex));
} catch (ResourceException $ex) {
    \DreamCommerce\Logger::error("An error occurred during Resource access: ".Client::getError($ex));
}

Token refreshing¶

use DreamCommerce\Exception\ClientException;

$config = require 'bootstrap.php';
try {
    $c = new \DreamCommerce\Client('https://myshop.example.com', $config['appId'], $config['appSecret']);
    $token = $c->refreshToken('INSERT TOKEN HERE');

    \DreamCommerce\Logger::info("Token has been successfully refreshed");
} catch (ClientException $ex) {
    \DreamCommerce\Logger::error("An error occurred during the Client request: ".$ex->getMessage());
}

requirements¶

This library requires following aspects of interpreter to be satisfied:

• PHP 5.3 or higher
• SSL support enabled
• allow_url_fopen flag set to on
• compiled JSON extension (in the most of cases, available out-of-the-box)

installation¶

There are two ways to get and install the SDK into application:

• using Composer - in project directory call composer require dreamcommerce/shop-appstore-lib
• manual archive extraction - download an archive and extract its contents into project directory

Handling billing system events¶

$handler = $this->handler = new Handler(
    'https://myshop.example.com', 'application ID', 'Secret', 'AppStore Secret'
);

$handler->subscribe('install', 'installHandler');   // function name
// $handler->subscribe('install', $installHandler);   // lambda
// $handler->subscribe('install', array($this, 'installHandler'));   // object method

//$handler->subscribe('billing_install', array($this, 'billingInstallHandler'));
//$handler->subscribe('billing_subscription', array($this, 'billingSubscriptionHandler'));
//$handler->subscribe('uninstall', array($this, 'uninstallHandler'));

Passed callback will be executed as an action handler.

Getting OAuth token¶

Token exchange is performed with the authorization key got during the application install.

The most convenient way is to exchange this code during the install. In billing system entry point it’s enough to use:

$client = new \DreamCommerce\Client(
    'https://myshop.example.com', 'application ID', 'Secret'
);

$token = $client->getToken('AUTH CODE');

// $token is an object with access_token, refresh_token, expires_in

The best is to store gathered tokens into the database - access_token is required every time an application gets access to the shop.

Refreshing the token¶

In case the token gets expired (look at: expires_in) or in case it’s invalidated, it’s possible to refresh it:

$client = new \DreamCommerce\Client(
    'https://myshop.example.com', 'Application ID', 'Secret'
);

$token = $client->refreshToken('REFRESH TOKEN');

// $token is an object with access_token, refresh_token, expires_in

This object has equal information to the example above.

Performing REST-ful request¶

With a valid token, it’s possible to perform request to the shop according to the API documentation:

$client = new \DreamCommerce\Client(
    'https://myshop.example.com', 'Application ID', 'Secret'
);

$client->setAccessToken('SHOP TOKEN');

// getting collection/object
$product = new \DreamCommerce\Resource\Product($client);
$list = $product->get();

foreach($list as $item){
    //...
}

// object update
$product->put(ID, array(...));

// create object
$product->post(array(...));

// delete object
$product->delete(ID);

static methods¶

static DreamCommerce\Client::getError(Exception $exception)¶

Returns an error message of specified exception, layer-independent.

Parameters:	$exception (Exception) – an exception which is a source for error message
Return type:	string
Returns:	error message

methods¶

DreamCommerce\Client::__construct($entrypoint, $clientId, $clientSecret)¶

constructor

Parameters:	$exception (string) – in case of webapi/rest is not a part of URL, it will be automatically appended $clientId (string) – string application ID $clientSecret (string) – application secret code (generated upon App Store application registration)

DreamCommerce\Client::__get($resource)¶

Returns resource object by name

Parameters:	$resource (string) – resource name
Return type:	resource

DreamCommerce\Client::getToken($authCode)¶

Gets token using the AuthCode.

Parameters:	$authCode (string) – authorization code, passed during installation
Return type:	array
Returns:	an array with tokens

DreamCommerce\Client::refreshToken($refreshToken)¶

Refreshes token

Parameters:	$refreshToken (string) – refresh token, passed during token getting/exchange
Return type:	array
Returns:	an array with new tokens

DreamCommerce\Client::request($res, $method, $objectPath = null, $data =, []$query =[])¶

Performs a request to the server

Parameters:	$res (Resource) – resource to perform request on $method (string) – GET/POST/PUT/DELETE $objectPath (null|string|array) – resource path, eg. object/1/something. It can be also an array - then class will automatically glue it with /. $data (array) – data to pass with request $query (array) – query string
Returns:	request response
Return type:	mixed

DreamCommerce\Client::setAccessToken($token)¶

Sets an access token for current script execution. Called automatically upon exchange/refreshing of token.

Parameters:	$token (string) – token

methods¶

DreamCommerce\Handler::__construct($entrypoint, $clientId, $secret, $appStoreSecret)¶

Class constructor

Parameters:	$entrypoint (string) – shop URL - in case of webapi/rest is not a part of URL, it will be automatically appended $clientId (string) – application ID $secret (string) – API key $appStoreSecret (string) – secret code

DreamCommerce\Handler::subscribe($event, $handler)¶

Subscribes a handler to the chosen event.

Parameters:	$event (string) – event type for handling by handler $handler (Callable) – a handler to call when subscribed event is fired. $handler will be called with one argument of event params. If handler returns false value, event propagation is stopped.

Available $event values:

• install - an application is being installed in shop
• uninstall - an application is being uninstalled
• billing_install - installation payment
• billing_subscription - subscription payment

DreamCommerce\Handler::unsubscribe($event, $handler = null)¶

Unsubscribes from event handling.

Parameters:	$event (string) – event type for handling by handler $handler (null|Callable) – if is null, all handlers are unbound. Specifying particular handler, leaves alone all except chosen.

Available $event values:

• install - an application is being installed in shop
• uninstall - an application is being uninstalled
• billing_install - installation payment
• billing_subscription - subscription payment

static methods¶

static DreamCommerce\Http::instance¶

Returns a class instance

Returns:	class instance
Return type:	Http

static DreamCommerce\Http::setRetryLimit($num)¶

Sets retries count if requests quota is exceeded.

Parameters:	$num (integer) – retries limit

methods¶

DreamCommerce\Http::delete($url[, $query = array()[, $headers = array()]])¶

Performs HTTP DELETE.

Parameters:	$url (string) – URL $query (array) – query parameters (URL query string, after question mark) $headers (array) – additional headers to sent within request
Return type:	array
Returns:	see: structure

DreamCommerce\Http::get($url[, $query = array()[, $headers = array()]])¶

Performs HTTP GET.

Parameters:	$url (string) – URL $query (array) – query parameters (URL query string, after question mark) $headers (array) – additional headers to sent within request
Return type:	array
Returns:	see: structure

DreamCommerce\Http::post($url[, $body = array()[, $query = array()[, $headers = array()]]])¶

Performs HTTP POST.

Parameters:	$url (string) – URL $body (string) – request body $query (array) – query parameters (URL query string, after question mark) $headers (array) – additional headers to sent within request
Return type:	mixed
Returns:	see: structure

DreamCommerce\Http::put($url[, $body = array()[, $query = array()[, $headers = array()]]])¶

Performs HTTP PUT.

Parameters:	$url (string) – URL $body (string) – request body $query (array) – query parameters (URL query string, after question mark) $headers (array) – additional headers to sent within request
Return type:	mixed
Returns:	see: structure

static methods¶

static DreamCommerce\Logger::__callStatic($name, $args)¶

calls static log method using $name as priority name and $args[0] as message

Parameters:	$name (string) – magic method name used as priority name $args (array) – arguments passed to magic method, $args[0] is treated as log message

Messages can be passed to simple logger class using multiple priorities:

\DreamCommerce\Logger::debug("debug message");
\DreamCommerce\Logger::info("informational message");
\DreamCommerce\Logger::notice("notice message");
\DreamCommerce\Logger::warning("warning message");
\DreamCommerce\Logger::error("error message");
\DreamCommerce\Logger::critical("critical message");
\DreamCommerce\Logger::alert("alert message");
\DreamCommerce\Logger::emergency("emergency message");

methods¶

DreamCommerce\Logger::log($message, $lvl = self::DEBUG)¶

Logs message to defined stream.

Parameters:	$message (string) – log message $lvl (string) – priority

The stream can be set by defining DREAMCOMMERCE_LOG_FILE constant

value	meaning
false	logging is disabled
string	file path or stream (i.e. php://stdout, logs/application.log)

You can define the constant in your source code:

define('DREAMCOMMERCE_LOG_FILE', "php://stdout");

By default, all the messages are added with debug priority. All those messages are by default filtered out, due to disabled debug mode. Debugging may be enabled by defining DREAMCOMMERCE_DEBUG constant.

value	meaning
false	debug mode is disabled
true	debug mode is enabled

You can define the constant in your source code:

define('DREAMCOMMERCE_DEBUG', true);

resources¶

static methods¶

static DreamCommerce\Resource::factory($client, $name)¶

instantiates new Resource object

Parameters:	$client (Client) – handle to the client library instance $name (string) – name of resource
Return type:	Resource

\DreamCommerce\Resource::factory($client, "product");

methods¶

DreamCommerce\Resource::delete([$id = null])¶

Deletes an object by ID.

Parameters:	$id (integer) – object ID
Return type:	boolean

DreamCommerce\Resource::filters($filters)¶

Filters records (GET only).

Chaining method - returns a handle to an object itself.

Parameters:	$filters (array) – an array of filters
Return type:	Resource
Returns:	chain

DreamCommerce\Resource::get([...])¶

Performs GET request.

Parameters:	.. (mixed) – arguments - no argument: returns collection - single argument - an object with specified ID - more arguments - resource dependent
Return type:	ResourceList|ArrayObject|string

DreamCommerce\Resource::getName()¶

Returns a plural name of resource.

Return type:	string

DreamCommerce\Resource::limit($count)¶

Restrict amount of fetched records of collection (GET only).

Chaining method - returns a handle to an object itself.

Parameters:	$count (integer) – count of records to fetch
Return type:	Resource
Returns:	chain

DreamCommerce\Resource::order($expr)¶

Sorts records by specified criteria (GET only).

Chaining method - returns a handle to an object itself.

Parameters:	$expr (string) – sorting expression, eg. field DESC, field ASC or +field, -field
Return type:	Resource
Returns:	chain

DreamCommerce\Resource::page($page)¶

Specifies results page number for fetching (GET only).

Chaining method - returns a handle to an object itself.

Parameters:	$page (integer) – number of page
Return type:	Resource
Returns:	chain

DreamCommerce\Resource::post([$data = array()])¶

Performs a POST request.

Chaining method - returns a handle to an object itself.

Parameters:	$data (array) – request body
Return type:	ArrayObject|string

DreamCommerce\Resource::put([$id = null[, $data = array()]])¶

Performs PUT request.

Chaining method - returns a handle to an object itself.

Parameters:	$id (null|integer) – ID of modified object $data (array) – request body
Return type:	ArrayObject|string

methods¶

DreamCommerce\ResourceList::__construct($array = array(), $flags = ArrayObject::ARRAY_AS_PROPS)¶

Creates a new class instance.

Parameters:	$array (array) – Objects in the collection $flags (integer) – flags for ArrayObject
Return type:	void

DreamCommerce\ResourceList::setCount($count)¶

set number of all resources on requested list.

Parameters:	$count (integer) – number of all resources on the list
Return type:	void

DreamCommerce\ResourceList::getCount()¶

get number of all resources on requested list.

Return type:	integer
Returns:	number of objects

DreamCommerce\ResourceList::setPage($page)¶

set current page number.

Parameters:	$page (integer) – current page number
Return type:	void

DreamCommerce\ResourceList::getPage()¶

get current page number.

Returns:	page number
Return type:	integer

DreamCommerce\ResourceList::setPageCount($count)¶

set total page count.

Parameters:	$count (integer) – total page count
Return type:	void

DreamCommerce\ResourceList::getPageCount()¶

get total page count.

Return type:	integer
Returns:	pages count