README

PHP Client library to connect with the Sendy API. This client lets you connect with the Sendy API to create shipments and labels.

Installation

Installing the client can be done through Composer:

composer require sendynl/php-sdk

Usage

Authentication

Authentication can be done in two different ways: with personal access tokens and the OAuth flow.

Personal Access Tokens

You can manage your personal access tokens in the portal. When you have a personal access token, you can use this library like this:

<?php

$connection = new \Sendy\Api\Connection();

$connection->setAccessToken('your-personal-access-token');

$connection->me->get();

OAuth

Authorize the connection from your app

$connection = new \Sendy\Api\Connection();

$connection->setOauthClient(true);

$connection->setClientId('your-client-id')
    ->setClientSecret('your-client-secret')
    ->setRedirectUrl('your-callback-url');

$connection->redirectForAuthorization();

This will redirect the user to the portal and authorize your integration with their account.

Connect with the API

$connection = new \Sendy\Api\Connection();

$connection->setClientId('your-client-id')
    ->setClientSecret('your-client-secret')
    ->setRedirectUrl('your-callback-url');

// Either an authorization code or a refresh token is required to fetch an access token
$connection->setAuthorizationCode('authorization-code');
$connection->setRefreshToken('refresh-token');

// Optional if you have alreay stored the access token in your application
$connection->setAccessToken('access-token');
$connection->setTokenExpires(1123581321);

$connection->me->get();

// Store the access token, refresh token en the expiration timestamp in your application to prevent unnecessary
// requesting new access tokens
$connection->getAccessToken();
$connection->getRefreshToken();
$connection->getTokenExpires();

Token refresh callback

It is possible to provide the connection a callable to execute when the tokens are refresh. This can be useful when you want to store the new tokens in your application to reuse them when necessary.

$connection = new \Sendy\Api\Connection();

$connection->setOauthClient(true);

$connection->setClientId('your-client-id')
    ->setClientSecret('your-client-secret')
    ->setRedirectUrl('your-callback-url')
    ->setTokenUpdateCallback(function (\Sendy\Api\Connection $connection) {
        $data = [
            'access_token' => $connection->getAccessToken(),
            'refresh_token' => $connection->getRefreshToken(),
            'token_expires' => $connection->getTokenExpires(),
        ];
        
        // Use this data to store the tokens in your application
    });

Transports

The Sendy PHP SDK uses a concept called "transports" to send the HTTP requests to the Sendy API. By default, the TransportFactory will pick a suitable Transport for the environment if you do not supply one.

If, for example, your application already has a specific HTTP client library available, you may want to provide your own transport implementation. To create your own transport, create a class that implements Sendy\Api\Http\Transport\TransportInterface.

use Illuminate\Foundation\Application;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Http;
use Sendy\Api\Exceptions\TransportException;
use Sendy\Api\Http\Request;
use Sendy\Api\Http\Response;
use Sendy\Api\Http\Transport\TransportInterface

class LaravelTransport implements TransportInterface
{
    public function send(Request $request): Response
    {
        $headers = $request->getHeaders();
        $contentType = Arr::pull($headers, 'Content-Type', 'application/json');

        try {
            $response = Http::withHeaders($headers)
                ->withBody($request->getBody(), $contentType)
                ->withMethod($request->getMethod())
                ->withUrl($request->getUrl())
                ->send();
        } catch (\Throwable $e) {
            throw new TransportException($e->getMessage(), $e->getCode(), $e);
        }

        return new Response($response->status(), $response->headers(), $response->body());
    }

    public function getUserAgent() : string
    {
        return 'LaravelHttpClient/' . Application::VERSION;
    }
}

To use your transport, set it on the connection:

$connection = new \Sendy\Api\Connection();

$connection->setTransport(new LaravelTransport());

Endpoints

The endpoints in the API documentation are mapped to the resource as defined in the Resources directory. Please consult the API documentation for detailed documentation.

Contributing

Please see CONTRIBUTING for details.

Security

If you've found a bug regarding security please mail security@sendy.nl instead of using the issue tracker.

License

The MIT License (MIT). Please see the License file for more information