Introduction

PHP SDK for Postmen API. For problems and suggestions please open GitHub issue

Table of Contents

• Installation
  • Requirements
  • Manual installation
  • Using Composer
• Quick Start
• class Postmen
  • Postmen($api_key, $region, $config = array())
  • create($resource, $payload, $config = array())
  • get($resource, $id = NULL, $query = array(), $config = array())
  • getError()
  • callGET($path, $query = array(), $options = array())
  • callPOST($path, $body = array(), $options = array())
  • callPUT($path, $body = array(), $options = array())
  • callDELETE($path, $body = array(), $options = array())
• Error Handling
  • class PostmenException
  • Automatic retry on retryable error
• Examples
  • Full list
  • How to run
  • Navigation table
• Testing
• License
• Contributors

Installation

Requirements

PHP version >= 5.3 is required. For SDK development PHP 5.6 is required (to run automated tests).

Tested on PHP 5.3, 5.4, 5.5, 5.6.

Manual installation

• Download the source code.
• Reference API class.

require('.../path/to/repository/src/Postmen/Postmen.php');

Using Composer

• If you don't have Composer, download and install
• You have 2 options to download the Postmen PHP SDK

Run the following command to require Postmen PHP SDK

composer require postmen/sdk-php

OR download the sorce code and run

composer install

• Autoload the postmen-php-sdk package.

$loader = require __DIR__ . '/vendor/autoload.php';

Quick Start

In order to get API key and choose a region refer to the documentation.

use Postmen\Postmen;

$api_key = 'YOUR_API_KEY';
$region = 'sandbox';

// create Postmen API handler object

$api = new Postmen($api_key, $region);

try {
	// as an example we request all the labels
	
	$result = $api->get('labels');
	echo "RESULT:\n";
	print_r($result);
} catch (exception $e) {
	// if error occurs we can access all
	// the details in following way
	
	echo "ERROR:\n";
	echo $e->getCode() . "\n";	// error code
	echo $e->getMessage() . "\n";	// error message
	print_r($e->getDetails());	// details
}

class Postmen

Postmen($api_key, $region, $config = array())

Initiate Postmen SDK object. In order to get API key and choose a region refer to the documentation.

Argument	Required	Type	Default	Description
$api_key	YES	String	N / A	API key
$region	NO if $config['endpoint'] is set	String	N / A	API region (sandbox, production)
$config	NO	Array	array()	Options
$config['endpoint']	—	String	N / A	Custom URL API endpoint
$config['retry']	—	Boolean	TRUE	Automatic retry on retryable errors
$config['rate']	—	Boolean	TRUE	Wait before API call if rate limit exceeded or retry on 429 error
$config['safe']	—	Boolean	FALSE	Suppress exceptions on errors, NULL would be returned instead, check Error Handling
$config['raw']	—	Boolean	FALSE	To return API response as a raw string
$config['array']	—	Boolean	FALSE	To return API response as an associative array
$config['proxy']	—	Array	array()	Proxy credentials
$config['proxy']['host']	YES if $config['proxy'] is not empty	String	N / A	Proxy host
$config['proxy']['port']	NO	Integer	N / A	Proxy port
$config['proxy']['username']	NO	String	N / A	Proxy user name
$config['proxy']['password']	NO	String	N / A	Proxy password

create($resource, $payload, $config = array())

Creates API $resource object, returns new object payload as Array.

Argument	Required	Type	Default	Description
$resource	YES	String	N / A	Postmen API resourse ('rates', 'labels', 'manifests')
$payload	YES	Array or String	N / A	Payload according to API
$config	NO	Array	array()	Override constructor config

API Docs:

• POST /rates
• POST /labels
• POST /manifests
• POST /cancel-labels

Examples:

• rates_create.php
• labels_create.php
• manifests_create.php
• cancel_labels_create.php

get($resource, $id = NULL, $query = array(), $config = array())

Gets API $resource objects (list or a single objects).

Argument	Required	Type	Default	Description
$resource	YES	String	N / A	Postmen API resourse ('rates', 'labels', 'manifests')
$id	NO	String	NULL	Object ID, if not set 'list all' API method is used
$query	NO	Array or String	array()	Optional parameters for 'list all' API method
$config	NO	Array	array()	Override constructor config

API Docs:

• GET /rates
• GET /rates/:id
• GET /labels
• GET /labels/:id
• GET /manifests
• GET /manifests/:id
• GET /cancel-labels
• GET /cancel-labels/:id

Examples:

• rates_retrieve.php
• labels_retrieve.php
• manifests_retrieve.php
• cancel_labels_retrieve.php

getError()

Returns SDK error, PostmenException type if $conifg['safe'] = TRUE; was set.

Check Error Handling for details.

callGET($path, $query = array(), $options = array())

Performs HTTP GET request, returns an Array object holding API response.

Argument	Required	Type	Default	Description
$path	YES	String	N / A	URL path (e.g. 'v3/labels' for https://sandbox-api.postmen.com/v3/labels )
$query	NO	Array or String	array()	HTTP GET request query string
$config	NO	Array	array()	Override constructor config

callPOST($path, $body = array(), $options = array())

callPUT($path, $body = array(), $options = array())

callDELETE($path, $body = array(), $options = array())

Performs HTTP POST/PUT/DELETE request, returns an Array object holding API response.

Argument	Required	Type	Default	Description
$path	YES	String	N / A	URL path (e.g. 'v3/labels' for https://sandbox-api.postmen.com/v3/labels )
$body	YES	Array or String	N / A	HTTP POST/PUT/DELETE request body
$config	NO	Array	array()	Override constructor config

Error Handling

Particular error details are listed in the documentation.

All SDK methods may throw an exception described below.

class PostmenException

Method	Return type	Description
getCode()	Integer	Error code
isRetryable()	Boolean	Indicates if error is retryable
getMessage()	String	Error message (e.g. The request was invalid or cannot be otherwise served)
getDetails()	Array	Error details (e.g. Destination country must be RUS or KAZ)

In case of $conifg['safe'] = TRUE; SDK would not throw exceptions, getError() must be used instead.

Example: error.php

Automatic retry on retryable error

If API error is retryable, SDK will wait for delay and retry. Delay starts from 1 second. After each try, delay time is doubled. Maximum number of attempts is 5.

To disable this option set $conifg['retry'] = FALSE;

Examples

Full list

All examples avalible listed in the table below.

File	Description
rates_create.php	rates object creation
rates_retrieve.php	rates object(s) retrieve
labels_create.php	labels object creation
labels_retrieve.php	labels object(s) retrieve
manifests_create.php	manifests object creation
manifests_retrieve.php	manifests object(s) retrieve
cancel_labels_create.php	cancel-labels object creation
cancel_labels_retrieve.php	cancel-labels object(s) retrieve
proxy.php	Proxy usage
error.php	Avalible ways to catch/get errors
response.php	Avalible output types

How to run

Download the source code, go to examples directory.

Put your API key and region to credentials.php

Check the file you want to run before run. Some require you to set additional variables.

Navigation table

For each API method SDK provides PHP wrapper. Use the table below to find SDK method and example that match your need.

Model \ Action	create	get all	get by id
rates	.create('rates', $payload, $opt)	.get('rates', NULL, NULL, $opt)	.get('rates', $id, NULL, $opt)
labels	.create('labels', $payload, $opt)	.get('labels', NULL, NULL, $opt)	.get('labels', $id, NULL, $opt)
manifest	.create('manifest', $payload, $opt)	.get('manifest', NULL, NULL, $opt)	.get('manifest', $id, NULL, $opt)
cancel-labels	.create('cancel-labels', $payload, $opt)	.get('cancel-labels', NULL, NULL, $opt)	.get('cancel-labels', $id, NULL, $opt)

Testing

If you contribute to SDK, run automated test before you make pull request.

phpunit --bootstrap tests/bootstrap.php tests/Postmen.php

License

Released under the MIT license. See the LICENSE file for details.

Contributors

• Sunny Chow - view contributions
• Marek Narozniak - view contributions