claassenmarius/laravel-skynet

A laravel package to use the Skynet Courier API

1.1.1 2021-06-27 20:25 UTC

Requires

• php: ^8.0
• guzzlehttp/guzzle: ^7.0
• illuminate/contracts: ^8.37

Requires (Dev)

• brianium/paratest: ^6.2
• nunomaduro/collision: ^5.3
• orchestra/testbench: ^6.0
• phpunit/phpunit: ^9.5
• spatie/laravel-ray: ^1.23
• vimeo/psalm: ^4.4

MIT

• Marius Claassen

• laravel
• claassenmarius
• skynet
• laravel-skynet

README

A Laravel package to use the Skynet Courier API.

Installation

Require the package using composer:

composer require claassenmarius/laravel-skynet

Usage

Add the following environment variables to your .env file and add your Skynet account username, password, system id and account number.

SKYNET_ACCOUNT_USERNAME=
SKYNET_ACCOUNT_PASSWORD=
SKYNET_SYSTEM_ID=
SKYNET_ACCOUNT_NUMBER=

You can obtain an instance of Claassenmarius\LaravelSkynet\Skynet in any of the following ways:

Type-hinting / Dependency injection

When type-hinting Skynet in a method, Laravel will automatically resolve it from the IOC container for you.

use Claassenmarius\LaravelSkynet\Skynet;

class QuoteController extends Controller
{
    public function __invoke(Skynet $skynet)
    {
        $response = $skynet->quote(...);
        
        // do somethin with the $response
    }    
}

Facade

You can use the Skynet Facade.

use Claassenmarius\LaravelSkynet\Facades\Skynet;

class QuoteController extends Controller
{
    public function __invoke()
    {
        $response = Skynet::quote(...);
        
        // do somethin with the $response
    }   
}

Manually resolving it from the IOC container

use Claassenmarius\LaravelSkynet\Skynet;

class QuoteController extends Controller
{
    public function __invoke()
    {
        $skynet = app()->make(Skynet::class);
        
        $response = $skynet->quote(...);
        
        // do somethin with the $response
    }   
}

Manual instantiation

If you plan on instantiating Skynet manually throughout your project it won't be neccessary to add your Skynet credentials to the .env file. Instead, pass your credentials to the constructor.

use Claassenmarius\LaravelSkynet\Skynet;

class QuoteController extends Controller
{
    public function __invoke()
    {
        $skynet = new Skynet(
          'skynet_username',
          'skynet_password',
          'skynet_system_id',
          'skynet_account_number'
        );
        
        $response = $skynet->quote(...);
        
        // do somethin with the $response
    }
}

The following methods are available to get a security token, validate a suburb/postcode combination, get a list of postal codes for a suburb, get a quote for a parcel, get an ETA between two locations, generate a waybill, obtain a POD image and track a waybill. Each method returns a new Illuminate\Http\Client\Response which exposes methods to inspect the response.

Get a security token

$response = $skynet->securityToken();

Validate a suburb and postal code combination

$response = $skynet->validateSuburbAndPostalCode([
    'suburb' => 'Brackenfell',
    'postal-code' => '7560'
]);

Get a list of postal codes for a suburb

$response = $skynet->postalCodesFromSuburb('Brackenfell');

Get a quote for a parcel

$response = $skynet->quote([
    'collect-city' => 'Brackenfell',
    'deliver-city' => 'Stellenbosch',
    'deliver-postcode' => '7600',
    'service-type' => 'ON1',
    'insurance-type' => '1',
    'parcel-insurance' => '0',    
    'parcel-length' => 10, //cm
    'parcel-width' => 20, // cm
    'parcel-height' => 30, //cm
    'parcel-weight' => 20 //kg
]);

Get ETA between two locations

$response = $skynet->deliveryETA([
    'from-suburb' => 'Brackenfell',
    'from-postcode' => '7560',
    'to-suburb' => 'Stellenbosch',
    'to-postcode' => '7600',
    'service-type' => 'ON1'
]);

Generate a waybill

$response = $skynet->createWaybill([
    "customer-reference" => "Customer Reference",
    "GenerateWaybillNumber" => true,
    "service-type" => "ON1",
    "collection-date" => "2021-06-26",
    "from-address-1" => "3 Janie Street, Ferndale, Brackenfell",
    "from-suburb" => "Brackenfell",
    "from-postcode" => "7560",
    "to-address-1" => "15 Verreweide Street, Universiteitsoord, Stellenbosch",
    "to-suburb" => "Stellenbosch",
    "to-postcode" => "7600",
    "insurance-type" => "1",
    "insurance-amount" => "0",
    "security" => "N",
    "parcel-number" => "1",
    "parcel-length" => 10,
    "parcel-width" => 20,
    "parcel-height" => 30,
    "parcel-weight" => 10,
    "parcel-reference" => "12345",
    "offsite-collection" => true
]);

Get a waybill POD Image

$response = $skynet->waybillPOD('your-waybill-number');

Track a waybill

$response = $skynet->trackWaybill('your-waybill-number');

Response

Illuminate\Http\Client\Response provides the following methods to inspect the response.

Get the body of the response as a string:

$securityToken = $response->body(); 
// "{"SecurityToken":"2_f77e4922-1407-485e-a0fa-4fdd5c29e9ca"}" 

Get the JSON decoded body of the response as an array or scalar value (if a $key is passed in)

$securityToken = $response->json($key); 
// ["SecurityToken" => "2_c767aa41-bca8-4084-82a0-69d8e27fba2c"] 

Get the JSON decoded body of the response as an object.

$securityToken = $response->object(); 
// { +"SecurityToken": "2_c767aa41-bca8-4084-82a0-69d8e27fba2c" }

Get the JSON decoded body of the response as a collection.

$securityToken = $response->collect($key); 

Get a header from the response.

$header = $response->header($header); 
// "application/json; charset=utf-8"

Get the headers from the response.

$headers = $response->headers(); 
// Return an array of all headers

Get the status code of the response.

$headers = $response->status(); 
// 200

Determine if the request was successful (Whether status code >=200 & <300)

$headers = $response->successful(); 
// true

Determine if the response code was "OK". (Status code === 200)

$headers = $response->ok(); 
// true

Determine if server error occurred. (Whether status code >=500)

$headers = $response->serverError(); 
// false

Determine if client or server error occurred.

$headers = $response->failed(); 
// false

You can inspect the Laravel documentation for more information on the methods that Illuminate\Http\Client\Response provide.

Exception Handling

This package uses Laravel's Http Client behind the scenes, which does not throw exceptions on client or server errors (400 and 500 level responses from servers). You may determine if one of these errors was returned using the successful, clientError, or serverError methods.

If you have a response instance and would like to throw an instance of Illuminate\Http\Client\RequestException if the response status code indicates a client or server error, you may use the throw method:

response = $skynet->quote(...);

if($response->failed()) {
// Throw an exception if a client or server error occurred...
  $response->throw();
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

License

The MIT Licence (MIT). Please see Licence File for more information.