Skip to content

PHP SDK CloudCore documentation

Jump to bottom
Vasyl Kushniruk edited this page Sep 6, 2022 · 3 revisions

Getting started

What is CloudCore PHP SDK

The Cloudprinter.com CloudCore PHP SDK is a library with useful features that enable developers to easily integrate their application or system with Cloudprinter.com and make requests to our CloudCore API. This PHP SDK makes it easy to set up the integration between your application and the Cloudprinter.com Print Cloud to request instant pricing, post-print orders, get production signals back, and more.

The CloudCore API is designed easy integration with any application or service.

We at Cloudprinter.com have connected 150+ printers to print & ship print products in almost any country in the world. Whether this is around the corner or on the other side of the globe, we've got you covered: we can deliver 500+ different products in more than 100 countries currently.

Our platform makes use of smart routing algorithms to route any print job to the most local and qualified printer. Based on location, performance, price and production options, your print job is routed by these algorithms to the nearest printing facility near your delivery address to help you save on transit times and costs.

Visit our website for more information on all the products and services that we offer.

Prerequisites

  • composer (for installation)
  • php 7.0 or above
  • json, fileinfo, curl extensions must be enabled
  • Cloudprinter.com Print Cloud account

How to install?

The CloudCore SDK can be installed with Composer. Run this command:

composer require cloudprinter/cloudcore

Or manual installation:

git clone -b master https://github.com/cloudprintercom/cloudcore-php-sdk

<?php
require '/path-to-sdk/autoload.php';

Quick start

Once you have completed the installation, you could make the first call. To write an app that uses the SDK, you will create your first PHP script that will create a CloudCore client. Look at Authentication to know how to get it.

use CloudPrinter\CloudCore\Client\CloudCoreClient;  
  
$apiKey = '***';  
$client = new CloudCoreClient($apiKey);

After the CloudApps client is created, you can work with cloudprinter api.

$response = $client->order->getList();
$orderList = $response->getData();

General

Authentication

Authentication is done via a predefined CloudCore API key. The CloudCore API key is found in the Cloudprinter.com Dashboard.

Error Handling

API errors.

Each API call via CloudCore SDK returns a Response object. To be sure that it succeeded you need to check the status code.

$apiKey = '***';  
$orderReference = '123';  
  
$client = new CloudCoreClient($apiKey);  
$response = $client->order->getInfo($orderReference);  

if ($response->getStatusCode() == 200) {
	print_r($response->getData());
}

Exception.

In a case of request, data is not valid, SDK throws ValidationException exception. here is an example how to handle this.

use CloudPrinter\CloudCore\Client\CloudCoreClient;
use CloudPrinter\CloudCore\Exception\ValidationException;
use CloudPrinter\CloudCore\Model\{Address, File, OrderItem, Order, Option};

$apiKey = '***';
$client = new CloudCoreClient($apiKey);

$address = new Address();
$address->setEmail('test@mail.com')
    ->setFirstName('John')
    ->setLastName('Doe')
    ->setCountry('NL')
    ->setCity('Amsterdam')
    ->setStreet('Street1')
    ->setPhone('+31-655-538-848')
    ->setZip('1071 JA')
    ->setType('delivery');

$fileCover = new File();
$fileCover->setUrl('https://s3-eu-west-1.amazonaws.com/demo.cloudprinter.com/b52f510a5e2419f67c4925153ec0c080_v2/CP_Sample_doc_A4_Book_Cover_Textbook_80_gsm_Casewrap_v2.1.pdf')
    ->setType('cover');

$fileBook = new File();
$fileBook->setUrl('https://s3-eu-west-1.amazonaws.com/demo.cloudprinter.com/b52f510a5e2419f67c4925153ec0c080_v2/CP_Sample_doc_A4_Book_Interior_Textbook_v2.1.pdf')
    ->setType('book');

$item = new OrderItem();
$item->setReference('item-1')
    ->setCount(1)
    ->setProduct('textbook_cw_a4_p_bw')
    ->setShippingLevel('cp_saver')
    ->addFile($fileCover)
    ->addFile($fileBook)
    ->addOption(new Option('cover_finish_gloss', 1))
    ->addOption(new Option('pageblock_80off', 1))
    ->addOption(new Option('cover_130mcg', 1))
    ->addOption(new Option('total_pages', 100));

$order = new Order();
$order
    ->setEmail('test@mail.com')
    ->setReference('sdk-' . time())
    ->addItem($item)
    ->addAddress($address);

try {
    $response = $client->order->create($order);
    print_r($response->getData());
} catch (ValidationException $e) {
    print_r($e->getValidationMessages());
}

Debugging

The model method toArray() returns the request API data. This information contains all data that will be used for API calls. Look at the example below.

use CloudPrinter\CloudCore\Client\CloudCoreClient;
use CloudPrinter\CloudCore\Model\Order;

$apiKey = '***';
$client = new CloudCoreClient($apiKey);

$order = new Order();
.............
var_dump($order->toArray());

$client->order->create($order);

Examples

Order

List all orders

Request the list of all orders.

use CloudPrinter\CloudCore\Client\CloudCoreClient;

$apiKey = '***';
$client = new CloudCoreClient($apiKey);
$response = $client->order->getList();

print_r($response->getData());

Get order info

Request detailed order info by reference.

use CloudPrinter\CloudCore\Client\CloudCoreClient;

$apiKey = '***';
$orderReference = 123;

$client = new CloudCoreClient($apiKey);
$response = $client->order->getInfo($orderReference);

print_r($response->getData());

Add order

Add a new order including one or more items, addresses, options, and files. Files should be added with a URL from where Cloudprinter can fetch the files when the order has been accepted. An MD5 hash of the file is not required, but if you have one it will save you time on calculating. Look for more details in Documentation.

use CloudPrinter\CloudCore\Client\CloudCoreClient;
use CloudPrinter\CloudCore\Exception\ValidationException;
use CloudPrinter\CloudCore\Model\{Address, File, OrderItem, Order, Option};

$apiKey = '***';
$client = new CloudCoreClient($apiKey);

$address = new Address();
$address->setEmail('test@mail.com')
    ->setFirstName('John')
    ->setLastName('Doe')
    ->setCountry('NL')
    ->setCity('Amsterdam')
    ->setStreet('Street1')
    ->setPhone('+31-655-538-848')
    ->setZip('1071 JA')
    ->setType('delivery');

$fileCover = new File();
$fileCover->setUrl('https://s3-eu-west-1.amazonaws.com/demo.cloudprinter.com/b52f510a5e2419f67c4925153ec0c080_v2/CP_Sample_doc_A4_Book_Cover_Textbook_80_gsm_Casewrap_v2.1.pdf')
    ->setType('cover');

$fileBook = new File();
$fileBook->setUrl('https://s3-eu-west-1.amazonaws.com/demo.cloudprinter.com/b52f510a5e2419f67c4925153ec0c080_v2/CP_Sample_doc_A4_Book_Interior_Textbook_v2.1.pdf')
    ->setType('book');

$item = new OrderItem();
$item->setReference('item-1')
    ->setCount(1)
    ->setProduct('textbook_cw_a4_p_bw')
    ->setShippingLevel('cp_saver')
    ->addFile($fileCover)
    ->addFile($fileBook)
    ->addOption(new Option('cover_finish_gloss', 1))
    ->addOption(new Option('pageblock_80off', 1))
    ->addOption(new Option('cover_130mcg', 1))
    ->addOption(new Option('total_pages', 100));

$order = new Order();
$order
    ->setEmail('test@mail.com')
    ->setReference('sdk-' . time())
    ->addItem($item)
    ->addAddress($address);

try {
    $response = $client->order->create($order);
    print_r($response->getData());
} catch (ValidationException $e) {
    print_r($e->getValidationMessages());
}

Reorder

Reorders use the regular order create method, they just require a few extra parameters. Reorders are done per item level. Only items from a single order can be included in a reorder. Look for more details in Documentation.

use CloudPrinter\CloudCore\Client\CloudCoreClient;
use CloudPrinter\CloudCore\Exception\ValidationException;
use CloudPrinter\CloudCore\Model\{Address, File, OrderItem, Order, Option};

$apiKey = '***';
$client = new CloudCoreClient($apiKey);

$address = new Address();
$address->setEmail('test@mail.com')
  ->setFirstName('John')
  ->setLastName('Doe')
  ->setCountry('NL')
  ->setCity('Amsterdam')
  ->setStreet('Street1')
  ->setPhone('+31-655-538-848')
  ->setZip('1071 JA')
  ->setType('delivery');

$fileCover = new File();
$fileCover->setUrl('https://s3-eu-west-1.amazonaws.com/demo.cloudprinter.com/b52f510a5e2419f67c4925153ec0c080_v2/CP_Sample_doc_A4_Book_Cover_Textbook_80_gsm_Casewrap_v2.1.pdf')
  ->setType('cover');

$fileBook = new File();
$fileBook->setUrl('https://s3-eu-west-1.amazonaws.com/demo.cloudprinter.com/b52f510a5e2419f67c4925153ec0c080_v2/CP_Sample_doc_A4_Book_Interior_Textbook_v2.1.pdf')
    ->setType('book');

$item = new OrderItem();
$item->setReference('item-1')
  ->setCount(1)
  ->setProduct('textbook_cw_a4_p_bw')
  ->setShippingLevel('cp_saver')
  ->addFile($fileCover)
  ->addFile($fileBook)
  ->setReorderItemReference('reorder-item-1')
  ->setReorderOrderReference('order-reference')
  ->setReorderCause('reorder cause')
  ->setReorderDescription('reorder description')
  ->addOption(new Option('cover_finish_gloss', 1))
  ->addOption(new Option('pageblock_80off', 1))
  ->addOption(new Option('cover_130mcg', 1))
  ->addOption(new Option('total_pages', 100));

$order = new Order();
$order
  ->setEmail('test@mail.com')
  ->setReference('sdk-' . time())
  ->addItem($item)
  ->addAddress($address);

try {
  $response = $client->order->create($order);
  print_r($response->getData());
} catch (ValidationException $e) {
  print_r($e->getValidationMessages());
}

Cancel order

Request cancellation of a specific order by reference.

use CloudPrinter\CloudCore\Client\CloudCoreClient;

$apiKey = '***';
$orderReference = '123';
$client = new CloudCoreClient($apiKey);
$response = $client->order->cancel($orderReference);

print_r($response->getData());

Order log

Request an order log by reference.

use CloudPrinter\CloudCore\Client\CloudCoreClient;

$apiKey = '***';
$orderReference = '123';

$client = new CloudCoreClient($apiKey);
$response = $client->order->getLog($orderReference);

print_r($response->getData());

Order quote

Request an order quote. Cloudprinter provides quotes on product prices, shipping options, and shipping prices through the quote API endpoint. Each quote request returns both product prices and shipping options with pricing. Each quote has its unique hash, which has to be included in the order. A quote is valid for 48 hours.

use CloudPrinter\CloudCore\Client\CloudCoreClient;
use CloudPrinter\CloudCore\Exception\ValidationException;
use CloudPrinter\CloudCore\Model\{Option, OrderQuote, OrderQuoteItem};

$apiKey = '***';
$client = new CloudCoreClient($apiKey);

$option = new Option();
$option->setType('paper_90off')
  ->setCount(1);

$itemQuote = new OrderQuoteItem();
$itemQuote->setReference('123')
  ->setCount(250)
  ->setProduct('letterheading_ss_a4_2_0')
  ->addOption($option);

$orderQuote = new OrderQuote();
$orderQuote->setCountry('NL')
    ->addItem($itemQuote);

try {
  $response = $client->order->quote($orderQuote);
  print_r($response->getData());
} catch (ValidationException $e) {
  print_r($e->getValidationMessages());
}

Get quote info

Request detailed information about a quote hash.

use CloudPrinter\CloudCore\Client\CloudCoreClient;

$apiKey = '***';
$quoteHash = '123';

$client = new CloudCoreClient($apiKey);
$response = $client->order->quoteInfo($quoteHash);

print_r($response->getData());

Product

List all products

Request a list of all cloudprinter products.

use CloudPrinter\CloudCore\Client\CloudCoreClient;

$apiKey = '***';
$client = new CloudCoreClient($apiKey);
$response = $client->product->getList();

print_r($response->getData());

Product info

Request detailed product information.

use CloudPrinter\CloudCore\Client\CloudCoreClient;

$apiKey = '***';
$productReference = 'folder_s150_s_fc';

$client = new CloudCoreClient($apiKey);
$response = $client->product->getInfo($productReference);

print_r($response->getData());

Getting help

If you get stuck, we're here to help. The following are the best ways to get assistance working through your issue:

Clone this wiki locally