onecommunity/client

PHP client to access the One Community API.

v0.10.0 2020-12-28 10:41 UTC

Requires

• php: ^7.2|^8.0
• jarnovanleeuwen/jwtapi: ^0.4.0

Requires (Dev)

• symfony/var-dumper: ^4.1

MIT

• Jarno van Leeuwen

• api
• onecommunity

README

An easy-to-use PHP client to access the One Community API.

Installation

Using Composer:

composer require onecommunity/client

Contact us with your public key to receive your API key.

Usage

Initializing the Client

use OneCommunity\Client;

$apiKey = "xxxxxxx";
$projectName = "yourproject";
$userId = 1;

$client = new Client($apiKey, $userId, $projectName);

// Load private key from file..
$client->loadPrivateKey("private_rsa.pem");
// ..or string
$client->setPrivateKey($privateKey);

Sending Requests

See the Examples directory for working examples.

UserRequest

Returns the User object of the authenticated user. Great for testing.

use OneCommunity\Requests\UserRequest;

$request = new UserRequest;
$response = $client->send($request);

if ($response->isSuccessful()) {
    var_dump($response->getData());
}

SendTransactionalMailRequest

use OneCommunity\Requests\SendTransactionalMailRequest;

$accountId = 1; // Recipient
$transactionalMailId = 1; // Mail

$request = new SendTransactionalMailRequest($accountId, $transactionalMailId);
$request->setSubstitutions(['gift' => 'Free coffee ☕']);

$response = $client->send($request);

Responses

The following HTTP status codes are used:

If anything unexpected occurs a OneCommunity\Exceptions\RequestException is thrown (e.g., if the API does not return a valid JSON response).

All responses (except 200 OK) contain a message attribute, explaining what went wrong. Furthermore, 400 Bad Requests responses contain a code attribute which can contain one of the following values:

The validation errors of a 422 Unprocessable Entity response are structured as follows:

{
    "errors": {
        "field1": [
            "error1",
            "error2"
        ],
        "field2": [
            "error3"
        ]
    }
}

Security

The API is based on JWT API, an efficient and secure machine-to-machine API using JSON Web Tokens and asymmetric request signing. Advantages of this approach include:

• Requests and responses are sent over a secure channel.
• Requests can only be signed by the API consumer (providing non-repudiation).
• Requests are only valid for a short time (avoiding replay attacks).

Due to the asymmetric nature of this protocol, a public/private key pair needs to be generated (RSA 2048 bit). The key pair can be generated by issuing the following commands. Please send your public key (public_rsa.pem) to us and keep your private key safe.

Generating the Public/Private Key Pair

# Generates RSA private key of 2048 bit size
openssl genrsa -out private_rsa.pem 2048

# Generates public key from the private key
openssl rsa -in private_rsa.pem -outform PEM -pubout -out public_rsa.pem