README

Table of Contents

• What is it?
• Requirements
• Installation
• Todo
• Configuration
  • Settings
  • Authentication Mode
  • Configuring with Environment Variables
  • Configuring with Constructor
  • Guzzle HTTP Options
• Getting your API Key
• Response
• Function Parameters
• Method Functions
  • GET
  • POST
  • PATCH
  • DELETE
• Request Method
• Filter
  • Condition Format
  • Example
  • Condition Functions
  • Operator Functions
• Getting your API key
• Uploading
• Error handling

What is it?

This is a small lightweight PHP client for using the REST API service of Billmax billing software.

Requirements

• PHP ^8.3
• guzzlehttp/guzzle ^7.15.2 || ^8.0.1
• ocolin/global-type ^2.0

Installation

composer require ocolin/billmax

Todo

• Add OAuth2 support
• Add more integration testing

Configuration

Settings

The client can be configured by either environment variables, constructor arguments, or a combination of both, Here is a list of the settings needed for configuration.

Authentication mode.

The Billmax REST API has 3 authentication modes:

• NONE - Uses only the Billmax remote application session ID
• USERPASS - Uses session ID of a staff employee via username/password
• OAUTH2 - Uses OAuth2 to authenticate. Not yet supported by this client.

Configuring with Environment variables.

// Manually setting variables for demonstration
$_ENV['BILLMAX_API_HOST']     = 'https://myhost.com:3100/api/billmaxCoreApi/v1/';
$_ENV['BILLMAX_API_KEY']      = 'GETTHISFROMSESSIONIDINREMOTEAPP';
$_ENV['BILLMAX_API_AUTH']     = 'USERPASS';
$_ENV['BILLMAX_API_USERNAME'] = 'staffmember';
$_ENV['BILLMAX_API_PASSWORD'] = 'staffmemberpassword';
$_ENV['BILLMAX_API_APP_ID']   = 'billmax-techapp';

$billmax = new Ocolin\BillMax\Billmax();

Configuring with constructor

The Billmax client uses a Config object class to hold settings. You can configure this by creating a Config object.

$config = new Ocolin\Billmax\Config(
        host: 'https://myhost.com:3100/api/billmaxCoreApi/v1/',
      apiKey: 'GETTHISFROMSESSIONIDINREMOTEAPP',
        auth: 'USERPASS',
    username: 'staffmember',
    password: 'staffmemberpassword',
       appId: 'billmax-techapp'
);

$billmax = new \Ocolin\Billmax\Billmax( $config: $config );

Guzzle HTTP options.

This client uses Guzzle to handle HTTP calls and allows for extra options to be specified in the Config object.

$config = new Ocolin\Billmax\Config(
    options: [
        'timeout' => 30,
        'verify'  => true
    ]
);

Response

The Billmax client will return a response object with the following properties:

Function Parameters

Method functions

GET

$response = $billmax->get(
    endpoint: '/accounts/{id}',
       query: [ 'id' => 1234 ]
);

POST

$response = $billmax->post(
    endpoint: '/aps',
        body: [
        'name' => 'AP name',
        'description' => 'AP description',
        'pop' => 'My POP',
        'maximumDownloadRate' => 1000
        'maximumUploadRate' => 1000,
        'fccTechnologyCode' => 'Other Wireline',
        'technology' => 'wireless'
    ]
);

PATCH

$response = $billmax->patch(
    endpoint: '/aps/{id}',
       query: [ 'id' => 1234 ],
        body: [ 'name' => 'Updated AP name' ],
     autoGet: true // Defaults to true, but showing for example
);

DELETE

$response = $billmax->delete(
    endpoint: '/aps/{id}',
       query: [ 'id' => 1234 ]
);

Request method

Also included is a generic function without a specific HTTP method.

$response = $billmax->request(
    endpoint: '/aps/{id}',
    method: 'PATCH',
    query: [ 'id' => 1234 ],
    body: [ 'name' => 'updated name' ]
);

Filter

The Billmax API has a query parameter that allows requests to be filtered. This class is to make creating filters easier by putting them in function calls rather than typing out a filter query.

A filter can have multiple conditions and each condiction consists of a field (a column in the database), an operator, and a value. The Filter allows these to be stacked together.

Condition format

Filter::where( name of columns )
    ->operatorFunction( value )
    ->build()

Filter::where( name of column1 )
    ->operator1( value )
    ->also( name of column2 )
    ->operator2( value )
    ->build()

Example

use Ocolin\Billmax\Filter;
$output = $billmax->get(
    endpoint: '/accounts',
    query: [
        'fltrs' => Filter::where( 'id' )
                          ->in( [1,2,3] )
                          ->also( 'state' )
                          ->ne( 1 )
                          ->build()
    ]   
);

Condition functions

Operator functions

Getting your API key.

The api ksy is part of your billmax remove application and was generated when you set up the remote application. Locating your API Key:

• Log into Billmax staff portal
• Under the System Administration menu, go to Remote Applications
• Click on the number next to your billmaxCoreApi app
• Copy the value from the Session Id field
• Click Generate Session Id if you want to create a new key.

Uploading

Because uploading files works much different from the rest of endpoints, a specific function as been created to handle file uploading. Note: Uploading will not re-try on failed authentication.

Upload arguments

File Path Properties

Each file takes an array of values:

Example

$output = $billmax->upload(
    entity: 'account',
    entityId: 1
    files: [
        [
            'path'        => __DIR__ '/file.txt',
            'class'       => 'support',
            'description' => 'My special file'
        ]
    ]
);

Error handling

HTTP error statuses are returned, not thrown

A 4xx or 5xx response from the server is not an exception. It comes back as a normal Response object, so you decide what counts as a success for your use case. A 404 after a delete might be exactly what you wanted.

$response = $billmax->get( endpoint: '/accounts/{id}', query: [ 'id' => 999999 ] );

if( $response->status === 404 ) {
    // account does not exist
}

The one exception is 401. If the server rejects the session, the client re-authenticates and retries the request once. If the retry is also rejected, an AuthException is thrown.

Exceptions

Everything the client throws at runtime extends one base class, so a single catch covers all of it.

All exceptions live in the Ocolin\Billmax\Exceptions namespace.

use Ocolin\Billmax\Exceptions\BillmaxException;

try {
    $response = $billmax->get( endpoint: '/accounts/{id}', query: [ 'id' => 1234 ] );
}
catch( BillmaxException $e ) {
    // anything the client can throw at runtime
}

Telling an outage from a rejection

An unreachable server throws ConnectionException. A refused login throws AuthException. Catch the specific class first:

use Ocolin\Billmax\Exceptions\AuthException;
use Ocolin\Billmax\Exceptions\BillmaxException;
use Ocolin\Billmax\Exceptions\ConnectionException;

try {
    $response = $billmax->get( endpoint: '/accounts' );
}
catch( ConnectionException $e ) {
    // could not reach the server
}
catch( AuthException $e ) {
    // credentials rejected, send the user back to log in
}
catch( BillmaxException $e ) {
    // everything else
}

ConnectionException means the request may not have reached the server. A timeout after the request was sent can still have been processed, so only retry operations that are safe to repeat (GET, DELETE). Be careful retrying a POST, which could create a duplicate.

The original Guzzle exception is available through getPrevious().