PHP Library

Welcome to the ShopRunBack public PHP library.

This library will help you use the ShopRunBack API easily in your PHP application.

It is used in our PrestaShop module.

If you have any question, please send an email to: tech_at_shoprunback.com

Install

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

Click here to download the library.

Then, unzip the .zip and move the folder into your project.

Finally, to load the library, you need to load it with a require_once.

Authentication

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

// We highly recommend you to write this line at the very beginning of your code
// This way, the token will be globally set for all API calls
\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

To use the API, you must be authenticated with your API token, which can be done with the class RestClient.

You need to set your API token in the RestClient with setToken, and then you will have access to all your data.

Elements

The elements are all the classes you can manipulate to display, edit or delete your personal data.

All the mandatory Elements required to create and manage a Shipback are implemented.

Account

The class Account represents your ShopRunBack account.

Get your account

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$account = \Shoprunback\Elements\Account::getOwn();

API Methods

Update your account

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$account = \Shoprunback\Elements\Account::getOwn();
$account->first_name = 'Martin';
$account->save();

Method	Enabled
Get all (paginated)	No
Get one	Yes, for your account only
Create	No
Update	Yes
Delete	No

Address

Initialize

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$address = new \Shoprunback\Elements\Address();

The class Address represents a postal address. It can belong to a Company, a Customer or a Warehouse.

Address is necessary to create a Warehouse or a Customer.

Create an Address

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

$address = new \Shoprunback\Elements\Address();

// Mandatory attributes
$address->line1 = '42, Noodle Boulevard';
$address->country_code = 'FR';
$address->city = 'Paris';

// Optional attributes
$address->line2 = '103 first floor';
$address->zipcode = '75001';

// We then attribute the Address to an appropriate element
$customer = new \Shoprunback\Elements\Customer();
$customer->address = $address;

Brand

Initialize

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$brand = new \Shoprunback\Elements\Brand();

The class Brand represents the brand you’re selling. Products belongs to a brand. You can create and delete Brands and add or remove Products from your Brands.

All your Products are linked to a Brand.

Create a Brand

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$brand = new \Shoprunback\Elements\Brand();

// Mandatory to create a new brand
$brand->name = 'My super brand';
$brand->reference = 'my-super-brand';

// Now we can save the brand!
$brand->save();

API Methods

Get all Brands (paginated)

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$brands = \Shoprunback\Elements\Brand::all();

Get a Brand

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$brand = \Shoprunback\Elements\Brand::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');

Update a Brand

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$brand = \Shoprunback\Elements\Brand::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');
$brand->name = 'New name';
$brand->save();

Delete a Brand

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

\Shoprunback\Elements\Brand::delete('1f27f9d9-3b5c-4152-98b7-760f56967dea');

Method	Enabled
Get all (paginated)	Yes
Get one	Yes
Create	Yes
Update	Yes
Delete	Yes

Company

Get its company

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$company = \Shoprunback\Elements\Company::getOwn();

The class Company contains the informations about your company.

API Methods

Update your company

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$company = \Shoprunback\Elements\Company::getOwn();
$company->name = 'ShopRunBack';
$company->save();

Method	Enabled
Get all (paginated)	No
Get one	Yes, your company only
Create	No
Update	Yes
Delete	No

Customer

Initialize

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$customer = new \Shoprunback\Elements\Customer();

The class Customer represents one of your customers.

Customer is necessary to create an Order or a Shipback.

Create a Customer

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

$customer = new \Shoprunback\Elements\Customer();

// Mandatory attributes
$customer->first_name = 'Jean';
$customer->last_name = 'Dupont';
$customer->email = 'jeandupont@gmail.com';
$customer->phone = '0612345789';

// Mandatory nested elements
// The mandatory nested elements must be filled with the required parameters.

// Please read the doc showing how to correctly create an Address.
$customer->address = new \Shoprunback\Elements\Address();

// Optional attributes
$customer->locale = 'fr';

// We then attribute the Customer to an appropriate element
$order = new \Shoprunback\Elements\Order();
$order->customer = $customer;

Item

Initialize

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$item = new \Shoprunback\Elements\Item();

The class Item represents a product a customer ordered with additionnal parameters specific to the order.

An Order owns an array of Items.

An Item is linked to a Product.

Create an Item

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

// The Item must be linked to a Product
$product = \Shoprunback\Elements\Product::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');

$item = new \Shoprunback\Elements\Item();

// Mandatory attributes
$item->product_id = $product->id;
$item->label = 'My item label'; // You can also set the product's label: $product->label
$item->reference = 'my-item-reference'; // You can also set the product's reference: $product->reference
$item->price_cents = 1000;

// Optional attributes
$item->barcode = '9782700507089';
$item->currency = 'eur';

// We then attribute the Item to an appropriate element
$order = new \Shoprunback\Elements\Order();
$order->items = [$item];

Order

Initialize

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

$order = new \Shoprunback\Elements\Order();

The class Order represents an online order made by one of your customers.

All orders have an array of items.

If the customer has asked to return some of the items, then the order is linked to a shipback.

Create an Order

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$order = new \Shoprunback\Elements\Order();

// Mandatory to create a new order
$order->order_number = '4548-9854';


// Mandatory nested elements
// The mandatory nested elements must be filled with the required parameters.

// Please read the doc showing how to correctly create a Customer.
$order->customer = new \Shoprunback\Elements\Customer();

// Please read the doc showing how to correctly create a Item.
$order->items = [];
$order->items[] = new \Shoprunback\Elements\Item();


// Optional
$order->metadata = ['foo' => 'bar'];

// Now we can save the order!
$order->save();

API Methods

Get all Orders (paginated)

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$orders = \Shoprunback\Elements\Order::all();

Get an Order

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$order = \Shoprunback\Elements\Order::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967deav');

Delete an Order

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

\Shoprunback\Elements\Order::delete('1f27f9d9-3b5c-4152-98b7-760f56967deav');

Method	Enabled
Get all (paginated)	Yes
Get one	Yes
Create	Yes
Update	No
Delete	Yes

Product

Initialize

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$product = new \Shoprunback\Elements\Product();

The class Product represents a product your company is selling. Do not confuse it with an Item.

All your products are linked to a brand. If you forget to link a product to a brand, it is then automatically linked to the default brand.

An Order has Items, and each Item is linked to one Product.

Create a Product

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$product = new \Shoprunback\Elements\Product();

// Mandatory to create a new product
$product->label = 'My super product';
$product->reference = 'my-super-product';
$product->weight_grams = 100;


// Mandatory nested elements
// The mandatory nested elements must be filled with the required parameters.

// If you want to link your product to an existing Brand, set the ID of your already registered brand
$product->brand_id = '1f27f9d9-3b5c-4152-98b7-760f56967dea';

// If you want to link your product to a new Brand
// Please read the documentation above showing how to correctly create a Brand.
$product->brand = new \Shoprunback\Elements\Brand();

// --------------------------------------------------------------------------------------
// To link a Brand, you must always either set brand_id or brand, but never both!
// --------------------------------------------------------------------------------------


// Optional
$product->ean = '1258987561456';
$product->width_mm = 100;
$product->length_mm = 100;
$product->height_mm = 100;
$product->metadata = ['foo' => 'bar'];

// For the picture, please use ONLY ONE of those two parameters, not both at the same time
$product->picture_file_base64 = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABAQAAAAA3bvkkAAAAAnRSTlMAAHaTzTgAAAAKSURBVHgBY2AAAAACAAFzdQEYAAAAAElFTkSuQmCC';
$product->picture_file_url = 'http://shoprunback.com/wp-content/themes/shoprunback/images/logo-menu.png';

// For Sparepart
$product->spare_parts =[];

$sparepart = new \Shoprunback\Elements\SparePart();
$sparepart->name = 'spare part test';
$sparepart->reference = 'SparePart-reference';

$product->spare_parts[] =  $sparepart;

// Now you can save the product
$product->save();

API Methods

Get all Products (paginated)

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$products = \Shoprunback\Elements\Product::all();

Get one Product

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$product = \Shoprunback\Elements\Product::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');

Update a Product

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$product = \Shoprunback\Elements\Product::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');
$product->label = 'New label';

$product->save();

Delete a Product

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

\Shoprunback\Elements\Product::delete('1f27f9d9-3b5c-4152-98b7-760f56967dea');

Delete a Product’s image

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

\Shoprunback\Elements\Product::deleteImage('1f27f9d9-3b5c-4152-98b7-760f56967dea');

Add SparePart to Exists Product

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$product = \Shoprunback\Elements\Product::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');

// For Sparepart
$product->spare_parts =[];

$sparepart = new \Shoprunback\Elements\SparePart();
$sparepart->name = 'spare part test';
$sparepart->reference = 'SparePart-reference';

$product->spare_parts[] =  $sparepart;

$product->save();

Method	Enabled
Get all (paginated)	Yes
Get one	Yes
Create	Yes
Update	Yes
Delete	Yes
Delete (image)	Yes

SparePart

Initialize

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$sparepart = new \Shoprunback\Elements\SparePart();

Create a SparePart

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$sparepart = new \Shoprunback\Elements\SparePart();

// Mandatory to create a new sparepart
$sparepart->name = 'My Part';
$sparepart->reference = 'my-spare-sparepart';
$sparepart->description = 'A longer description for your spare part';
$sparepart->picture_url = 'string'; 
$sparepart->metadata = ['foo' => 'bar'];

// Now you can save the sparepart
$sparepart->save();

Get all SpareParts (Not Available)

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$sparepart = \Shoprunback\Elements\SparePart::all();

Get one SparePart

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$sparepart = \Shoprunback\Elements\SparePart::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');

Update a SparePart

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$sparepart = \Shoprunback\Elements\SparePart::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');
$sparepart->name = 'New Name';
$sparepart->save();

Delete a SparePart

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

\Shoprunback\Elements\SparePart::delete('1f27f9d9-3b5c-4152-98b7-760f56967dea');

Method	Enabled
Get all (paginated)	No
Get one	Yes
Create	Yes
Update	Yes
Delete	Yes

ReturnedItem

Get ReturnedItems

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

$shipback = \Shoprunback\Elements\Shipback::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');

$returnedItem = $shipback->returned_items;

The class ReturnedItem represents an item a customer ordered and wants to return.

A Shipback owns an array of ReturnedItems.

A ReturnedItems is linked to an Item.

Shipback

Initialize

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$shipback = new \Shoprunback\Elements\Shipback();

The class Shipback represents a return request made by a customer.

All shipbacks are linked to an order. They also have an array of quotes given by the logistics service (see Quotes for more info), an array of returned items and a size set by the customer after the shipback was created.

The returned items is an array containing the selected items from the original order.

The quotes is an array of Quotes, meaning the available modes of transportation for the return, with their price, state and their related data.

The customer is the customer that has initially made the linked order.

The company is the company that owns the products inside the items the customer bought in the linked order.

Create a Shipback

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$shipback = new \Shoprunback\Elements\Shipback();

// Mandatory attributes
$shipback->order_id = '1f27f9d9-3b5c-4152-98b7-760f56967deav';

// ---------------------------------------------------------------------------------------------------------
// To create a shipback, you must only set an order_id. All the other attributes are created by ShopRunBack.
// ---------------------------------------------------------------------------------------------------------

// -----------------------------------------------------------------------------------
// To create a shipback, you must have at least one Warehouse created on your account!
// -----------------------------------------------------------------------------------


// Optional
$shipback->metadata = ['foo' => 'bar'];

// Now we can save the shipback!
$shipback->save();

API Methods

Get all Shipbacks (paginated)

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$shipbacks = \Shoprunback\Elements\Shipback::all();

Get one Shipback

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$shipback = \Shoprunback\Elements\Shipback::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967deav');

Delete a Shipback

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

\Shoprunback\Elements\Shipback::delete('1f27f9d9-3b5c-4152-98b7-760f56967deav');

Method	Enabled
Get all (paginated)	Yes
Get one	Yes
Create	Yes
Update	Yes
Delete	Yes

Warehouse

Initialize

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$warehouse = new \Shoprunback\Elements\Warehouse();

The class Warehouse represents the destination of the items that will be returned to you.

Create a Warehouse

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$warehouse = new \Shoprunback\Elements\Warehouse();

// Mandatory to create a new warehouse
$warehouse->name = 'My warehouse';
$warehouse->reference = 'my-warehouse';

// Now we can save the warehouse!
$warehouse->save();

API Methods

Get all Warehouses (paginated)

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$warehouses = \Shoprunback\Elements\Warehouse::all();

Get one Warehouse

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$warehouse = \Shoprunback\Elements\Warehouse::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');

Method	Enabled
Get all (paginated)	Yes
Get one	Yes
Create	Yes
Update	No
Delete	No

Manage a single Element

Use the library’s classes

Calling the class with a use statement

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

use \Shoprunback\Elements\Product as LibProduct;

$product = new LibProduct();

Calling the class without a use statement

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$product = new \Shoprunback\Elements\Product();

You can either call the class directly with its namespace or write a use statement so you can access it with the class name only.

We recommend you to use the use statement for your classes needing one of the library’s classes, since you will often call them.

For files calling the library’s classes rarely, you can use the direct call with the namespace.

Original values

Get original values

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$product = \Shoprunback\Elements\Product::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');

echo $product->label; // Prints: 'My label'

$product->label = 'New label';

echo $product->label; // Prints: 'New label'

echo $product->_origValues->label; // Prints 'My label'

$product->refresh();

echo $product->label; // Prints 'My label'

$product->label = 'New label';

$product->save();

echo $product->_origValues->label; // Prints 'New label'

You can get the original values of an Element whenever you want by getting the _origValues attribute.

If you want to reset an element with its original values, use refresh (makes an API call)

How to delete an Element

Remove an Element by an instance

require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$brand = \Shoprunback\Elements\Brand::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');
$brand->remove();

Remove an Element directly with its ID

require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

\Shoprunback\Elements\Brand::delete('1f27f9d9-3b5c-4152-98b7-760f56967dea');

You can either delete an Element by an instance with remove or directly with its ID with delete.

Get different attributes

Different ways to get important attributes

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$product = new \Shoprunback\Elements\Product();

$product->label = 'My label';
$product->custom = 'My custom param';
$product->brand = new \Shoprunback\Elements\Brand();

$product->getAllAttributes(); // Returns 'label', 'custom' and 'brand' with their values
$product->getApiAttributes(); // Returns 'label' and 'brand' with their values

To get all the attributes of an Element including the nested Elements, you can use getAllAttributes.

To get only the attributes an Element will use for an API call, you can use getApiAttributes.

Get all keys an Element accepts

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$product = new \Shoprunback\Elements\Product();

$product->getApiAttributesKeys(); // Returns all attributes a Product will accept before doing an API call

You can list all the attributes an Element accepts when making an API call with getApiAttributesKeys.

Use the elements with my objects

Separate my own classes and the library’s classes

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

use \Shoprunback\Elements\Product as libProduct;

class myProduct
{
  public function __construct()
  {
    $this->label = 'My label';
    $this->reference = 'my-label';
    $this->weight_in_grams = 1000;
  }

  public function generateLibProduct()
  {
    $product = new libProduct();

    $product->label = $this->label;
    $product->reference = $this->reference;
    $product->weight_in_grams = $this->weight_in_grams;

    //[...]
    // Add all params to $product
    //[...]

    return $product;
  }

  public function save()
  {
    // [...]

    $libProduct = $this->generateLibProduct();
    $libProduct->save();

    // [...]
  }
}

$myProduct = new myProduct();
$myProduct->save();

Extend the library’s classes

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

use \Shoprunback\Elements\Product as libProduct;

class myProduct extends libProduct
{
  public function __construct($params)
  {
    $this->label = $params['label'];
    $this->reference = $params['reference'];
    $this->weight_in_grams = $params['weight_in_grams'];

    //[...]
    // Add all params to $product
    //[...]

    if (isset($params['id']) && !is_null($params['id'])) {
      parent::__construct($params['id']);
    } else {
      parent::__construct();
    }
  }

  // Be careful not to overwrite the functions of the parent class!
  public function saveProduct()
  {
    // Code...

    $this->save(); // save() is a function of the parent class, don't overwrite it!

    // Code...
  }
}

$params = [
  'label' => 'My label',
  'reference' => 'my-label',
  'weight_in_grams' => 1000,
];

$myProduct = new myProduct($params);
$myProduct->saveProduct();

You can either use the library independantly of your classes or extend the library’s classes

Check changed fields

Check if an Element is a new one or not

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$product = new \Shoprunback\Elements\Product();
$product->isPersisted(); // false

$product->label = 'New label';
$product->reference = 'new-label';
$product->weight_in_grams = 1000;
$product->isPersisted(); // false

$product->save();
$product->isPersisted(); // true

$retrievedProduct = \Shoprunback\Elements\Product::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');
$retrievedProduct->isPersisted(); // true

Check changed fields in a existing Product

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$product = \Shoprunback\Elements\Product::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');

$product->isDirty(); // false
$product->getDirtyKeys(); // Returns []
$product->isKeyDirty('label'); // false

$product->label = 'New label';

$product->isDirty(); // true
$product->getDirtyKeys(); // Returns ['label']
$product->isKeyDirty('label'); // true

Check changed fields in a new Product

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

$product = new \Shoprunback\Elements\Product();
$product->isDirty(); // true

$product->label = 'My label';
$product->isDirtyKey('label'); // true
$product->getDirtyKeys(); // Returns ['label']

To know if an Element is new, you can use isPersisted. If it returns true, then the Element is not new.

You can check if an Element is new or has at least one parameter changed with isDirty.

You can know which keys have been changed with getDirtyKeys.

You can also check if a precise key has changed with isDirtyKey.

When you try to update an existing Element, it will only send the attributes that has been changed.

A key present in the getApiAttributesKeys that hasn’t a _origValues is considered changed (ex: when you create a new Product and add a label).

Which API calls can it do ?

Check which API calls an Element can or cannot do

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

// All those methods return true or false
\Shoprunback\Elements\Product::canRetrieve(); // Check if you can get one element
\Shoprunback\Elements\Product::canCreate(); // Check if you can save a new element
\Shoprunback\Elements\Product::canUpdate(); // Check if you can update an existing element
\Shoprunback\Elements\Product::canDelete(); // Check if you can delete an element
\Shoprunback\Elements\Product::canGetAll(); // Check if you can get many elements at once

You can check if an element can do an API call with canRetrieve(),canCreate(), canUpdate(), canDelete(), canGetAll()

Get the element name

Get the element name

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\Elements\Address::getElementName(); // Returns 'address'
\Shoprunback\Elements\Brand::getElementName(); // Returns 'brand'
\Shoprunback\Elements\Item::getElementName(); // Returns 'item'
\Shoprunback\Elements\Order::getElementName(); // Returns 'order'
\Shoprunback\Elements\Product::getElementName(); // Returns 'product'
\Shoprunback\Elements\Shipback::getElementName(); // Returns 'shipback'
\Shoprunback\Elements\Warehouse::getElementName(); // Returns 'warehouse'

To easily get the lowercase name of an element, you can use those methods.

Get a nested element with its name

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

$product = \Shoprunback\Elements\Product::retrieve('1f27f9d9-3b5c-4152-98b7-760f56967dea');

$brandName = \Shoprunback\Elements\Brand::getElementName(); // $brandName = 'brand'

$product->$brandName; // $product->brand

This way, you can easily get the attribute name for a nested Element. It can be useful in recursive functions or logs.

RestClient

Use the RestClient globally

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

$restClient = \Shoprunback\RestClient::getClient();
$restClient->useSandboxEnvironment();
$restClient->setToken('yourApiToken');

define('SRB_REST_CLIENT', $restClient);

Accepts: GET ; POST ; PUT ; DELETE

The RestClient is used to execute the API calls.

It is a Singleton, so you need to use getClient to use it.

Set token

Set token

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

$restClient = \Shoprunback\RestClient::getClient();
$restClient->setToken('yourApiToken');

You can set the token of a user with setToken(). Most of the API calls need you to be authentified to be done.

Use production or sandbox environment

Set environment

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

$restClient = \Shoprunback\RestClient::getClient();

$restClient->useProductionEnvironment();
// OR
$restClient->useSandboxEnvironment();

To choose which environment to work with, you can use useProductionEnvironment or useSandboxEnvironment.

It will define https://dashboard.shoprunback.com or https://sandbox.dashboard.shoprunback.com as the base URL for all the API calls.

Get the environments’ URL

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getProductionUrl(); // Returns 'https://dashboard.shoprunback.com'
\Shoprunback\RestClient::getSandboxUrl(); // Returns 'https://sandbox.dashboard.shoprunback.com'

If you want to get the URL of the production or sandbox environment without changing the environment you are working with, you can use getProductionUrl or getSandboxUrl.

Custom headers

Set custom headers

Set custom headers

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setCustomHeaders([
  'Custom-Field: Custom value',
  'Another-Field: Another value'
]);

If you need to add headers to your HTTP requests, you can add custom headers to your RestClient with setCustomHeaders.

Your custom headers must be an array.

Get your custom headers

Get your custom headers

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->getCustomHeaders();

You can get the custom headers you set with getCustomHeaders.

RestResponse

Success

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

try {
  $response = $restClient->request(
    \Shoprunback\Elements\Product::showEndpoint('1f27f9d9-3b5c-4152-98b7-760f56967dea'),
    \Shoprunback\RestClient::GET
  );
} catch(RestClientError $e) {

}

$response->getCode(); // Returns the HTTP code
$response->getBody(); // Returns the result of the API call (Here it returns the product with the id '1f27f9d9-3b5c-4152-98b7-760f56967dea')

Failure

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

try {
  $product = \Shoprunback\Elements\Product::retrieve('a wrong ID');
} catch (\Shoprunback\Error\Error $e) {
  if (is_a($e, \Shoprunback\Error\RestClientError)) {
    $response = $e->response;

    $response->getCode(); // Returns the HTTP code
    $response->getErrors(); // Returns the errors
  }
}

The RestResponse contains the response of an API call.

Parameter	Type	Description	Special
code	INT	The HTTP code returned
body	Object	The result of a succesful query	Only on Success
errors	Object	The result of a failed query	Only on Failure

Errors

Catch an Error from the library

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

try {
  $product = \Shoprunback\Elements\Product::retrieve('a wrong ID');
} catch (\Shoprunback\Error\Error $e) {
  // Here you can manage the error
}

To prevent errors to crash your application, you must catch the exceptions.

All the errors the library can return inherit from the class \Shoprunback\Error\Error.

Parameters

Parameter	Type	Description	Specific to
message	String	The mandatory message for an Exception	All
response	RestResponse	The response from the server explaining why the call failed	RestClientError

Error types

Use a RestClientError

<?php
require_once 'path/to/lib/shoprunback-php/init.php';

\Shoprunback\RestClient::getClient()->setToken('yourApiToken');

try {
  $product = \Shoprunback\Elements\Product::retrieve('a wrong ID');
} catch (\Shoprunback\Error\Error $e) {
  if (is_a($e, \Shoprunback\Error\RestClientError)) {
    $restResponse = $e->response;
    // Then, see how to use a RestResponse
  }
}

Class name	Event	Special
ElementCannotBeCreated	When an element doesn’t have a POST endpoint (ex: Account)
ElementCannotBeUpdated	When an element doesn’t have a PUT endpoint (ex: Order)
ElementCannotGetAll	When an element doesn’t have a GET endpoint to get all Elements (ex: Account)
ElementIndexDoesntExists	When you try to get the nth element and there are less than n element
NotFoundError	When you try to get or update an element but the given ID or reference doesn’t exist
RestClientError	When an error occured while trying to make an API call (token not set, server unreachable…)	Has a response parameter containing a RestResponse
UnknownApiToken	(Not yet implemented)
UnknownElement	When the library checks if an object is an Element and doesn’t find any appropriate class

Logs

Most actions of the library are logged.

You can check all those logs in /path/to/lib/shoprunback-php/logs.