library sdk-php

postmen/sdk-php

PHP for Postmen API. This extension helps developers to integrate with Postmen easily.

Introduction

PHP SDK for Postmen API. For problems and suggestions please open GitHub issue, _(*1)

Table of Contents, _(*2)

• 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)., _(*3)

Tested on PHP 5.3, 5.4, 5.5, 5.6., _(*4)

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, _(*5)

composer require postmen/sdk-php

OR download the sorce code and run, _(*6)

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., _(*7)

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., _(*8)

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

Creates API $resource object, returns new object payload as Array., _(*9)

API Docs: - POST /rates - POST /labels - POST /manifests - POST /cancel-labels, _(*10)

Examples: - rates_create.php - labels_create.php - manifests_create.php - cancel_labels_create.php, _(*11)

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

Gets API $resource objects (list or a single objects)., _(*12)

API Docs: - GET /rates - GET /rates/:id - GET /labels - GET /labels/:id - GET /manifests - GET /manifests/:id - GET /cancel-labels - GET /cancel-labels/:id, _(*13)

Examples: - rates_retrieve.php - labels_retrieve.php - manifests_retrieve.php - cancel_labels_retrieve.php, _(*14)

getError()

Returns SDK error, PostmenException type if $conifg['safe'] = TRUE; was set., _(*15)

Check Error Handling for details., _(*16)

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

Performs HTTP GET request, returns an Array object holding API response., _(*17)

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., _(*18)

Error Handling

Particular error details are listed in the documentation., _(*19)

All SDK methods may throw an exception described below., _(*20)

class PostmenException

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

Example: error.php, _(*22)

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., _(*23)

To disable this option set $conifg['retry'] = FALSE;, _(*24)

Examples

Full list

All examples avalible listed in the table below., _(*25)

How to run

Download the source code, go to examples directory., _(*26)

Put your API key and region to credentials.php, _(*27)

Check the file you want to run before run. Some require you to set additional variables., _(*28)

Navigation table

For each API method SDK provides PHP wrapper. Use the table below to find SDK method and example that match your need., _(*29)

Testing

If you contribute to SDK, run automated test before you make pull request., _(*30)

phpunit --bootstrap tests/bootstrap.php tests/Postmen.php, _(*31)

License

Released under the MIT license. See the LICENSE file for details., _(*32)

Contributors

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