README

Scrada PHP SDK

This SDK provides convenient, fully-typed access to Scrada's API.

Installation

You can install the package via composer:

composer require masmerise/scrada-php-sdk

Getting started

You can always refer to the documentation to examine the various resources that are available.

Setup

use Scrada\Authentication\Credentials;
use Scrada\Scrada;

$credentials = Credentials::present(
    key: '4844a45c-33d1-4937-83f4-366d36449eaf', 
    password: 'SajA1NOEphxVMwTTFzrDswj3AQkEGCCJ',
); 

$scrada = Scrada::authenticate($credentials);

Data retrieval

use Scrada\Company\Type\Primitive\CompanyId;

$company = CompanyId::fromString('4ccc0005-0bdd-430b-8f45-264c3f1a2a02'); 
$company = $scrada->company->get($company);

Resource update

use Scrada\CashBook\Type\Primitive\CashBookId;
use Scrada\CashBook\Type\Primitive\CodaGenerationPeriod;
use Scrada\CashBook\Type\Primitive\Name;
use Scrada\CashBook\Update\UpdateCashBook;
use Scrada\Company\Type\Primitive\CompanyId;

$companyId = CompanyId::fromString('4ccc0005-0bdd-430b-8f45-264c3f1a2a02');

$cashBookId = CashBookId::fromString('d84835b0-7125-4f8f-b10a-957a0cc73089');

$data = UpdateCashBook::parameters(
    name: Name::fromString('Acme Inc.'),
    codaGenerationPeriodType: CodaGenerationPeriod::EveryDay,
);

$scrada->cashBook->update($companyId, $cashBookId, $data);

Failures (exception handling)

The SDK uses exceptions as its medium to communicate failures.

ScradaException
├── UnknownException (Connection Errors)
└── ScradaApiException (Request Errors)
    ├── CouldNotGetCompany
    ├── CouldNotUpdateCompany
    ├── CouldNotGetAllCashBooks
    ├── CouldNotUpdateCashBook
    └── ...

use Scrada\Company\Get\Failure\CouldNotGetCompany;

try {
    $company = $scrada->company->get($id);
} catch (CouldNotGetCompany $ex) {
    $logger->log($ex->getMessage());
}

API failures

API interaction failures, i.e. exceptions of type ScradaApiException, always expose a special ScradaError object that contains the API's reasons for rejection:

use Scrada\Company\Get\Failure\CouldNotGetCompany;

try {
    $company = $scrada->company->get($id);
} catch (CouldNotGetCompany $ex) {
    $scradaError = $ex->error;

    $logger->log($scradaError->defaultFormat); // Localized error text
}

Rate limiting

The SDK is equipped with out-of-the-box capabilities to deal with Scrada's request constraints. In order to make use of this, you will have to provide a PSR-16 compatible cache store so the SDK can keep track of its current state.

Chances are that you are going to use this SDK in conjunction with a popular web framework, and most of them already have a PSR-16 compatible implementation of a cache store available:

$store = Container::getInstance()->get('cache');

$scrada = Scrada::authenticate(
    Credentials::present(...)
)->withStore($store);

Localization

You can use one of the available methods to change the API's language:

Dutch

$scrada->useDutch();

English (default)

$scrada->useEnglish();

French

$scrada->useFrench();

Environment

You can use one of the available methods to change the API's environment:

Production (default)

$scrada->useProduction();

Test

$scrada->useTest();

Retries

The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retriable and the number of retry attempts has not grown larger than the default retry limit (2).

A request is deemed retriable when any of the following HTTP status codes is returned:

408 (Timeout)
429 (Too Many Requests)
5XX (Internal Server Errors)

Timeouts

The SDK defaults to a 10 second timeout.

Implementation progress

Resource	Action
Cash book	Get all cash books
	Update cash book
Company	Get company
	Update company

While the SDK is battle-tested and production-ready, only a handful of API interactions have been implemented thus far. Please bear in mind this is an unofficial SDK, so we have to prioritize available resources at this time.

However, always feel free to submit a feature or pull request!

Testing

composer test

Changelog

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

Security

If you discover any security related issues, please email support@masmerise.be instead of using the issue tracker.

Credits

License

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

masmerise / scrada-php-sdk

Maintainers

Details