PortaBilling API

ESPF extends BillingBase
in package

Wrapper for ESPF API

The class is intended to provide interface to Portaone ESPF API. It handles authorisation, access token management and ESPF call handling. It needs: ConfigInterface object as billing server host, account and dependencies source.

The difference ESPF to API call is that ESPF returns HTTP 40x codes in a case of request failure. These codes will throw PortaESPFException. Meaning of each code depends of endpoint called.

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

Table of Contents

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
checkSession()  : void
Does active sesson check to billing server, relogin if required
delete()  : void
DELETE ESPF request
get()  : array<string|int, mixed>
GET ESPF request
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.
post()  : array<string|int, mixed>
POST ESPF request
put()  : array<string|int, mixed>
PUT ESPF request
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

Constants

DATETIME_FORMAT

Billing API datetime format

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

Methods

__construct()

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

public __construct(ConfigInterface $config) : mixed

On construct:

  • Check the cached 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

Return values
mixed —

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
Tags
throws
PortaAuthException

on relogin failed or no credentilas

Return values
void —

delete()

DELETE ESPF request

public delete(string $endpoint) : void

DELETE has no params, only endpoint. It returns HTTP 200 on success and 40x on failure, so the methid wil return nothing on success and throw PortaESPFException on error.

Parameters
$endpoint : string

endpoint to call

Tags
throws
PortaESPFException

on ESPF api error, check error coode with API docs

Return values
void —

get()

GET ESPF request

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

Params will be encoded and send as query string

Parameters
$endpoint : string

endpoint to call

$params : array<string|int, mixed> = []

associative array of params, may omit

Tags
throws
PortaESPFException

on ESPF api error, check error coode with API docs

Return values
array<string|int, mixed> —

associative array for returned JSON

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
Tags
throws
PortaAuthException
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.

Tags
throws
PortaConnectException
Return values
void —

post()

POST ESPF request

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

Params will be encoded and sent as JSON body

Parameters
$endpoint : string

endpoint to call

$params : array<string|int, mixed> = []

associative array of params, may omit

Tags
throws
PortaESPFException

on ESPF api error, check error coode with API docs

Return values
array<string|int, mixed> —

associative array for returned JSON or empty array on empty billing answer

put()

PUT ESPF request

public put(string $endpoint, array<string|int, mixed> $params) : array<string|int, mixed>

Params are mandatory and will be encoded and sent as JSON body

Parameters
$endpoint : string

endpoint to call

$params : array<string|int, mixed>

associative array of params, mandatory

Tags
throws
PortaESPFException

on ESPF api error, check error coode with API docs

Return values
array<string|int, mixed> —

associative array for returned JSON.

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 —

Search results