billforward/bf-php

BillForward PHP Client Library

Usage

Install (via Composer)

Our library can be installed via the Composer package manager., _(*1)

Add us to your composer.json:, _(*2)

{
    "require": {
        "billforward/bf-php": "1.*"
    }
}

Install the new package:, _(*3)

composer.phar install

Now include our code. Either use Composer's autoloader:, _(*4)

require_once('vendor/autoload.php');

Or include manually:, _(*5)

require_once('/path/to/vendor/billforward/bf-php/lib/BillForward.php');

Install (manually)

Step 1. Put our library into your repository

Inside lib/, lives: * BillForward.php * BFPHPClient/, _(*6)

Put these files in your repository., _(*7)

Step 2. Include our library from your code

Point to where BillForward.php is in your repository:, _(*8)

require_once('path/to/BillForward.php');

This file will autoload the library., _(*9)

Invocation

Use credentials to connect to BillForward

Step 1. Getting BillForward credentials

Login to (or Register) your BillForward Sandbox account., _(*10)

Grab a Private API token., _(*11)

Step 2. Connect to BillForward using BillForwardClient

Having included BillForward.php, you can now make an instance of BillForwardClient., _(*12)

It can be used as the default client for all requests:, _(*13)

$access_token = 'YOUR ACCESS TOKEN HERE';
$urlRoot = 'https://api-sandbox.billforward.net:443/v1/';
$client = new BillForwardClient($access_token, $urlRoot);
BillForwardClient::setDefaultClient($client);

Step 3. Make API calls using BillForwardClient

Construction of any BillForwardClient automatically registers that client as the 'default client'., _(*14)

Requests can now be made. These use the 'default client' implicitly:, _(*15)

$accounts = Bf_Account::getAll();

You can also explicitly specify a client. This is useful when connecting using multiple clients -- i.e. when migrating a user's data:, _(*16)

// use null queryparams, and specify the client to use for the request
$accounts = Bf_Account::getAll(null, $client);

Examples

See ExampleUsage.php for a full use-case of interacting with the API., _(*17)

View the examples in our PHP Client Library Docs., _(*18)

We provide also in the test folder some tests that show usage., _(*19)

Compatibility

The BillForward PHP Client Library is expected to work on PHP 5.3+. Required PHP extensions include:, _(*20)

cURL
json_decode

Building (for devs)

We use a build system. This is Gradle., _(*21)

We use a package manager. This is Composer., _(*22)

Mostly the build system is used for interacting with / invoking Composer., _(*23)

The build system provides these powers: * Ability to run tests * Composer installs phpunit * Composer generates classmap for tests to find our source code * Ability to regenerate project's 'autoload' classmap (for example if you add a class) * Composer generates classmap * Build system redraws Billforward.php autoloader from that classmap, _(*24)

How to build

To get the workspace setup, there are three steps:, _(*25)

1. Install and add to PATH: java, curl, php
2. Install gradle
3. Run gradle setup

Step 1. Installing Java, curl and PHP.

These are well-documented; follow normal installation process., _(*26)

UNIX users will already have curl. Windows users might want to look http://curl.haxx.se/dlwiz/?type=bin&os=Win32&flav=-&ver=*., _(*27)

Step 2. Installing gradle.

This step installs our build system, Gradle., _(*28)

Brave users can skip to Step 3; gradle will self-install itself if it needs to, _(*29)

(Requires Java on PATH)., _(*30)

We provide a Gradle self-installer for Windows and UNIX., _(*31)

It is in the build directory., _(*32)

Invoke with:, _(*33)

cd build
./gradlew

Step 3. Run gradle setup

This step runs a 'setup' build, which:, _(*34)

1. Self-installs Composer (if necessary)
2. Installs Composer packages (if necessary). [Classmap is also generated at this time]
3. Creates BillForward.php autoloader from that classmap

(Requires CURL on PATH: to self-install Composer)., _(*35)

(Requires PHP on PATH: to invoke Composer)., _(*36)

We provide a Composer self-installer for Windows and UNIX. Invoke with:, _(*37)

cd build
./gradlew setup

Running tests (for devs)

Setup

Tests login using the credentials you define in: test/BFPHPClientTest/new/config.php. A config.example.php is provided to guide you in creating this file., _(*38)

Ideally the credentials should refer to an account that exists solely for testing, as tests cause side-effects (entities created upon your organization)., _(*39)

Step 1. Register on Sandbox

Login to (or Register) a Sandbox account, that you are happy with using for tests., _(*40)

Grab a Private API token., _(*41)

Step 2. Create a config.php inside test/BFPHPClientTest/new/

<?php
$credentials = array(
    'urlRoot' => 'https://api-sandbox.billforward.net:443/v1/',
    'access_token' => 'INSERT_ACCESS_TOKEN_HERE'
    );

We use phpunit as our testrunner. If you have run ./gradlew setup, you will find already a phpunit binary in vendor/bin/phpunit., _(*42)

Invocation

(Requires phpunit on PATH)., _(*43)

To run all tests, cd to the repository root and invoke:, _(*44)

phpunit

phpunit will read phpunit.xml to find tests and find which classes to autoload., _(*45)

The tests themselves rely on vendor/bin/autoload.php (generated by Composer) to find their dependencies., _(*46)

Run individual file

A custom Sublime script can be used, for example (requires phpunit on PATH):, _(*47)

{
    "cmd": ["phpunit", "$file"],
    "selector": "source.php"
}

Or just invoke normally from anywhere using the terminal:, _(*48)

phpunit AccountTest.php

As with the full run, phpunit will climb the project structure looking for phpunit.xml., _(*49)

Making changes (for devs)

After adding, renaming or moving a class (ie, changing the classmap), use the build system to regenerate the autoloader BillForward.php and its classmap., _(*50)

Specifically, cd into /build and invoke:, _(*51)

./gradlew regenerateClassmap recompileClasspath

The newly-generated BillForward.php should be part of any commit., _(*52)

Confirm also that the usual unit test run passes (run phpunit from the project root). Refer to the 'Setup' section for instructions on configuring your test run., _(*53)

Release automation

Calculates date and major/minor version of release, generates and names zipped release in root dir, tags commit with version string, pushes tag., _(*54)

You will still need to go to GitHub and draft a release of the tagged commit (so you can add release notes and attach the zipped file)., _(*55)

New major version:, _(*56)

cd build
sh ./releaseHelpers/release incrementMajorVer

Same major version:, _(*57)

cd build
sh ./releaseHelpers/release

Untag latest release:, _(*58)

cd build
sh ./releaseHelpers/delete