PortaBilling API

Billing extends BillingBase
in package

Billing

Billing API wrapper

The class is intended to provide interface to Portaone billing API. It handles authorisation, access token management and API call handling. It needs:

ConfigInterface object as billing server host, account and call options configuration.
SessionStorageInterface object to store session data between invocanions.

See 'API documentation' section on https://docs.portaone.com

DATETIME_FORMAT = 'Y-m-d H:i:s': Billing API datetime format
__construct() : mixed: Setup the class, load (if any) saved session state and get it ready to use
call() : array<string|int, mixed>: Perform billing API call.
callAsync() : void: Perform bulk async billig call, running multiple concurrent requests at once.
callList() : array<string|int, mixed>: Call and return the next-level array if there only one key on the first level
checkSession() : void: Does active sesson check to billing server, relogin if required
getUsername() : string|null: Return current user login name
isSessionPresent() : bool: Returns true if session data exit and not expired
login() : void: Do login and setup the session.
logout() : void: Closes the session explicitly.
timeToBilling() : string: Return billing API string at UTC fro given Datetime object
timeToLocal() : DateTime: Convert billing-supplied UTC time string to DateTime object with target timezone

DATETIME_FORMAT

Billing API datetime format


    public
        mixed
    DATETIME_FORMAT
    = 'Y-m-d H:i:s'

__construct()

Setup the class, load (if any) saved session state and get it ready to use


    public
                    __construct(ConfigInterface $config[, SessionStorageInterface|null $storage = null ]) : mixed

On construct:

Loads saved session data from given SessinStorage object
Check the session token expire time within margin or left
If token expire soon (within configured margin), try to refresh token
If token expired or refresh failed - try to relogin if account data present, throwing exceptions on failures.
If no accoount data present, just left the class un-logged-in, then you need login() to get it connected

Parameters

$config : ConfigInterface: Configuration object to run
$storage : SessionStorageInterface|null = null: Session storage object to provide session persistance. SessionNoStorage used if null given.

Return values

mixed —

call()

Perform billing API call.


    public
                    call(string $endpoint[, array<string|int, mixed> $params = [] ]) : array<string|int, mixed>

Reference to your billing system API docs, located at https://your-billing-sip-host/doc/api/ or API section of Portaone docs site https://docs.portaone.com/. Mind your billing release version.

Parameters

$endpoint : string: API endpoint as per docs, exapmle: '/Customer/get_customer_info'
$params : array<string|int, mixed> = []: API requst data to put into "params" section

Return values

array<string|int, mixed> —

Billing system answer, converted to associative array. If billing retuns file, returns array with keys:

$returned = [
    'filename' => 'Invoice1234.pdf', // string, returned file name,
    'mime' => 'application/pdf',     // string, MIME file type
    'stream' => Stream               // PSR-7 stream object with file
];

callAsync()

Perform bulk async billig call, running multiple concurrent requests at once.


    public
                    callAsync(iteratable<string|int, mixed> $operations[, int $concurency = 20 ]) : void

Method crawling recursively the traversable given to find all AsyncOperationInterface objects and then process it in parallel with given concurrency (default 20). After run, the objects filled with answers or exceptions depending of each separate call results. it is safe as if there no object, it just do nothing silently, but still do a session check call.

On every callAsync() will first check session state with active call to the biling (/Session/ping) to avoid time wasting and return of all object filled with error due of broken sesson state. If the session fail and credentials present, it will try relogin. If no credential or login filed, it will throw PortaAuthException.

Parameters

$operations : iteratable<string|int, mixed>: array or any other multi-level iterable, containing objects, implementing AsyncOperationInterface
$concurency : int = 20: how much calls to run in parallel. Default is 20.

WARNING: due of some reasons increasing of concurrency over some empiric value does not decrease overall time to complete all the requests and even make it longer. In fact, PHP does not support async operations, so all the magic comes from cURL multi-call, so it could be combination of limitations: cURL, PortaOne server and PHP itlself. As for me, 20 works fine.

Return values

void —

callList()

Call and return the next-level array if there only one key on the first level


    public
                    callList(string $endpoint[, array<string|int, mixed> $params = [] ]) : array<string|int, mixed>

Same as call(), but if API returns an array with one element (mostly answers has just one key like 'customer_list'), it will cut one level and return the list itself. If the Billing returns more that one element on the top level, it returns the whole array. Sample:

// Instead of:
$answer = [
    'customer_list' => [
        {customer data here}
    ]
];
// it will return enclosed array:
$answer = [
    {customer data here}
];

Use with care as the return depends of API call params and may be unexpectable

Parameters

$endpoint : string: API endpoint as per docs, exapmle: '/Customer/get_customer_info'
$params : array<string|int, mixed> = []: API requst data to put into "params" section

Return values

array<string|int, mixed> —

Billing system answer, converted to associative array, cut one level if the returned array has only one key on the top level. If billing retuns file, returns array with keys:

$answer = [
    'filename' => 'Invoice1234.pdf', // string, returned file name,
    'mime' => 'application/pdf',     // string, MIME file type
    'stream' => Stream               // PSR-7 stream object with file
];

checkSession()

Does active sesson check to billing server, relogin if required


    public
                    checkSession() : void

Completes 'Session/ping' call to check session state, then:

If session not recognised, and credentials present, trying to relogin
If no credentials in config or login failure - throws auth exception

Return values

void —

getUsername()

Return current user login name


    public
                    getUsername() : string|null

Returns username taken from access token or null if no session is up

Return values

string|null —

isSessionPresent()

Returns true if session data exit and not expired


    public
                    isSessionPresent() : bool

Returns true if session data (token) exists and not expired, false if not logged in for any reason.

Does not complete active sesion check to the server. Due of serveer configuratioin issues token may be invalidated for inactivity before it's expire time really has come. So, positive isSessionUp() only means persistent session data loaded,

Return values

bool —

login()

Do login and setup the session.


    public
                    login(array<string|int, mixed> $account) : void

The session data will be stored if session storage class is supplied

Parameters

$account : array<string|int, mixed>

Account record to login to the billing. Combination of login+password or login+token required

$account = [
    'login' => 'myUserName',    // Mandatory username
    'password' => 'myPassword', // When login with password
    'token' => 'myToken'        // When login with API token

Return values

void —

logout()

Closes the session explicitly.


    public
                    logout() : void

Will call '/Session/logout' api method. Due of some problems with Portaone resposes, session will considered closed whatever server respond. No server error will be respected, but conenction errors will thrown.

Return values

void —

timeToBilling()

Return billing API string at UTC fro given Datetime object


    public
            static        timeToBilling(DateTimeInterface $time) : string

The DateTime obhject given will not change.

Parameters

$time : DateTimeInterface: Datetime object to take time from

Return values

string —

Billing API-type datetime string, shifted to UTC

timeToLocal()

Convert billing-supplied UTC time string to DateTime object with target timezone


    public
            static        timeToLocal(string $billingTime[, string $timezone = 'UTC' ]) : DateTime

Parameters

$billingTime : string

datetime string as billing returns

$timezone : string = 'UTC'

timezone string like 'Europe/London" or '+3000', as defined at https://www.php.net/manual/en/datetimezone.construct.php

Return values

DateTime —

Billing extends BillingBase in package Billing

Table of Contents

Constants

DATETIME_FORMAT

Methods

__construct()

Parameters

Return values

call()

Parameters

Tags

Return values

callAsync()

Parameters

Tags

Return values

callList()

Parameters

Tags

Return values

checkSession()

Tags

Return values

getUsername()

Return values

isSessionPresent()

Return values

login()

Parameters

Tags

Return values

logout()

Tags

Return values

timeToBilling()

Parameters

Return values

timeToLocal()

Parameters

Return values

Billing extends BillingBase
in package

Billing