/stuart-client-php

Stuart PHP client
  1. PHP 100.0%
PHP
Switch branches/tags
Nothing to show
Find file
Clone or download

Clone with HTTPS

Use Git or checkout with SVN using the web URL.

Download ZIP

Launching GitHub Desktop...

If nothing happens, download GitHub Desktop and try again.

Launching GitHub Desktop...

If nothing happens, download GitHub Desktop and try again.

Launching Xcode...

If nothing happens, download Xcode and try again.

Launching Visual Studio...

If nothing happens, download the GitHub extension for Visual Studio and try again.

Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src/Stuart
tests/Stuart/tests
.gitignore
CONTRIBUTING.md
LICENSE
README.md
composer.json
phpunit.xml.dist

README.md

Codeship Status for StuartApp/stuart-client-php

Stuart PHP Client

For a complete documentation of all endpoints offered by the Stuart API, you can visit Stuart API documentation.

Install

Via Composer:

$ composer require stuartapp/stuart-client-php

Usage

  1. Initialize Client
  2. Create a Job
    1. Minimalist
    2. Complete
      1. With scheduling at pickup
      2. With scheduling at drop off
      3. With stacking (multi-drop)
  3. Get a Job
  4. Cancel a Job
  5. Validate a Job
  6. Cancel a delivery
  7. Get a pricing
  8. Get a job eta to pickup
  9. Custom requests

Initialize client

$environment = \Stuart\Infrastructure\Environment::SANDBOX;
$api_client_id = '65176d7a1f4e734f6723hd690825f166f8dadf69fb40af52fffdeac4593e4bc'; // can be found here: https://admin-sandbox.stuart.com/client/api
$api_client_secret = '681ae68635c7aadef5cd1jdng8ef357a808cd9dc794811296446f19268d48fcd'; // can be found here: https://admin-sandbox.stuart.com/client/api
$authenticator = new \Stuart\Infrastructure\Authenticator($environment, $api_client_id, $api_client_secret);

$httpClient = new \Stuart\Infrastructure\HttpClient($authenticator)

$client = new \Stuart\Client($httpClient);

You can also pass your own Guzzle client instance to the \Stuart\HttpClient constructor:

$guzzleClient = new \Guzzle\Client();
$httpClient = new \Stuart\Infrastructure\HttpClient($authenticator, $guzzleClient);

This can be useful if you need to attach middlewares to the Guzzle client.

Create a Job

Important: Even if you can create a Job with a minimal set of parameters, we highly recommend that you fill as many information as you can in order to ensure the delivery process goes well.

Minimalist

Package size based
$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small');
    
$client->createJob($job);
Transport type based (France only)
$job = new \Stuart\Job();

$job->setTransportType('bike');

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$job->addDropOff('156 rue de Charonne, 75011 Paris');
    
$client->createJob($job);

Complete

Package size based
$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris')
    ->setComment('Wait outside for an employee to come.')   
    ->setContactCompany('KFC Paris Barbès')                
    ->setContactFirstName('Martin')                         
    ->setContactLastName('Pont')                          
    ->setContactPhone('+33698348756');                     

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small')
    ->setComment('code: 3492B. 3e étage droite. Sonner à Durand.')
    ->setContactCompany('Durand associates.')
    ->setContactFirstName('Alex')
    ->setContactLastName('Durand')
    ->setContactPhone('+33634981209')
    ->setPackageDescription('Pizza box.')
    ->setClientReference('12345678ABCDE'); // Must be unique
    
$client->createJob($job);
Transport type based (France only)
$job = new \Stuart\Job();

$job->setTransportType('bike');

$job->addPickup('46 Boulevard Barbès, 75018 Paris')
    ->setComment('Wait outside for an employee to come.')   
    ->setContactCompany('KFC Paris Barbès')                
    ->setContactFirstName('Martin')                         
    ->setContactLastName('Pont')                          
    ->setContactPhone('+33698348756');                     

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setComment('code: 3492B. 3e étage droite. Sonner à Durand.')
    ->setContactCompany('Durand associates.')
    ->setContactFirstName('Alex')
    ->setContactLastName('Durand')
    ->setContactPhone('+33634981209')
    ->setPackageDescription('Pizza box.')
    ->setClientReference('12345678ABCDE'); // Must be unique
    
$client->createJob($job);

With scheduling at pickup

For more information about job scheduling you should check our API documentation.

$job = new \Stuart\Job();

$pickupAt = new \DateTime('now', new DateTimeZone('Europe/London'));
$pickupAt->add(new \DateInterval('PT2H'));

$job->addPickup('46 Boulevard Barbès, 75018 Paris')
    ->setPickupAt($pickupAt);

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small');
    
$client->createJob($job);

With scheduling at dropoff

For more information about job scheduling you should check our API documentation.

Please note that this feature can only be used with only one dropoff.

$job = new \Stuart\Job();

$dropoffAt = new \DateTime('now', new DateTimeZone('Europe/London'));
$dropoffAt->add(new \DateInterval('PT2H'));

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small')
    ->setDropoffAt($dropoffAt);
    
$client->createJob($job);

With stacking (multi-drop)

Package size based
$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris')
    ->setComment('Wait outside for an employee to come.')   
    ->setContactCompany('KFC Paris Barbès')                
    ->setContactFirstName('Martin')                         
    ->setContactLastName('Pont')                          
    ->setContactPhone('+33698348756');                     

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small')
    ->setComment('code: 3492B. 3e étage droite. Sonner à Durand.')
    ->setContactCompany('Durand associates.')
    ->setContactFirstName('Alex')
    ->setContactLastName('Durand')
    ->setContactPhone('+33634981209')
    ->setPackageDescription('Red packet.')
    ->setClientReference('12345678ABCDE'); // Must be unique;
    
$job->addDropOff('12 avenue claude vellefaux, 75010 Paris')
    ->setPackageType('small')
    ->setComment('code: 92A42. 2e étage gauche')
    ->setContactFirstName('Maximilien')
    ->setContactLastName('Lebluc')
    ->setContactPhone('+33632341209')
    ->setPackageDescription('Blue packet.')
    ->setClientReference('ABCDE213124'); // Must be unique
    
$client->createJob($job);
Transport type based (France only)
$job = new \Stuart\Job();

$job->setTransportType('bike');

$job->addPickup('46 Boulevard Barbès, 75018 Paris')
    ->setComment('Wait outside for an employee to come.')   
    ->setContactCompany('KFC Paris Barbès')                
    ->setContactFirstName('Martin')                         
    ->setContactLastName('Pont')                          
    ->setContactPhone('+33698348756');                     

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setComment('code: 3492B. 3e étage droite. Sonner à Durand.')
    ->setContactCompany('Durand associates.')
    ->setContactFirstName('Alex')
    ->setContactLastName('Durand')
    ->setContactPhone('+33634981209')
    ->setPackageDescription('Red packet.')
    ->setClientReference('12345678ABCDE'); // Must be unique;
    
$job->addDropOff('12 avenue claude vellefaux, 75010 Paris')
    ->setComment('code: 92A42. 2e étage gauche')
    ->setContactFirstName('Maximilien')
    ->setContactLastName('Lebluc')
    ->setContactPhone('+33632341209')
    ->setPackageDescription('Blue packet.')
    ->setClientReference('ABCDE213124'); // Must be unique
    
$client->createJob($job);

Get a Job

Once you successfully created a Job you can retrieve it this way:

$jobId = 126532;
$job = $client->getJob($jobId);

Or when you create a new Job:

$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small');
    
$jobWithRoute = $client->createJob($job);

$jobWithRoute->getDeliveries();

The Stuart API determine the optimal route on your behalf, that's why the getDeliveries() method will return an empty array when the Job has not been created yet. The getDeliveries() method will return an array of Delivery as soon as the Job is created.

Cancel a job

Once you successfully created a Job you can cancel it in this way:

$jobId = 126532;
$result = $client->cancelJob($jobId);

The result will hold the boolean value true if the job was cancelled. If there was an error, it will contain an error object.

For more details about how cancellation works, please refer to our dedicated documentation section.

Validate a Job

Before creating a Job you can validate it (control delivery area & address format). Validating a Job is optional and does not prevent you from creating a Job.

$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small');
    
$result = $client->validateJob($job);

The result will hold the boolean value true if the job is valid. If there was an error, it will contain an error object.

Cancel a delivery

Once you successfully created a Delivery you can cancel it in this way:

$deliveryId = 126532;
$result = $client->cancelDelivery($deliveryId);

Get a pricing

Before creating a Job you can ask for a pricing. Asking for a pricing is optional and does not prevent you from creating a Job.

$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small');
    
$pricing = $client->getPricing($job);

$pricing->amount; // example: 11.5
$pricing->currency; // example: "EUR"

Get a job ETA to pickup

Before creating a Job you can ask for an estimated time of arrival at the pickup location (expressed in seconds). Asking for ETA is optional and does not prevent you from creating a job.

$job = new \Stuart\Job();

$job->addPickup('46 Boulevard Barbès, 75018 Paris');

$job->addDropOff('156 rue de Charonne, 75011 Paris')
    ->setPackageType('small');
    
$eta = $client->getEta($job);

$eta->eta; // example: 672

Custom requests

You can also send requests on your own without relying on the \Stuart\Client. It allows you to use endpoints that are not yet available on the \Stuart\Client and enjoy the \Stuart\Authenticator.

$apiResponse = $httpClient->performGet('/v2/jobs?page=1');
$apiResponse->success();
$apiResponse->getBody();