Download the PHP package billforward/bf-php without Composer

Usage

Install (via Composer)

Our library can be installed via the Composer package manager.

Add us to your composer.json:

Install the new package:

Now include our code. Either use Composer's autoloader:

Or include manually:

Install (manually)

Step 1. Put our library into your repository

Inside lib/, lives:

• BillForward.php
• BFPHPClient/

Put these files in your repository.

Step 2. Include our library from your code

Point to where BillForward.php is in your repository:

This file will autoload the library.

Invocation

Use credentials to connect to BillForward

Step 1. Getting BillForward credentials

Login to (or Register) your BillForward Sandbox account.

Grab a Private API token.

Step 2. Connect to BillForward using BillForwardClient

Having included BillForward.php, you can now make an instance of BillForwardClient.

It can be used as the default client for all requests:

Step 3. Make API calls using BillForwardClient

Construction of any BillForwardClient automatically registers that client as the 'default client'.

Requests can now be made. These use the 'default client' implicitly:

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

Examples

See ExampleUsage.php for a full use-case of interacting with the API.

View the examples in our PHP Client Library Docs.

We provide also in the test folder some tests that show usage.

Compatibility

The BillForward PHP Client Library is expected to work on PHP 5.3+. Required PHP extensions include:

Building (for devs)

We use a build system. This is Gradle.

We use a package manager. This is Composer.

Mostly the build system is used for interacting with / invoking Composer.

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

How to build

To get the workspace setup, there are three steps:

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.

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

Step 2. Installing gradle.

This step installs our build system, Gradle.

Brave users can skip to Step 3; gradle will self-install itself if it needs to

(Requires Java on PATH).

We provide a Gradle self-installer for Windows and UNIX.

It is in the build directory.

Invoke with:

Step 3. Run gradle setup

This step runs a 'setup' build, which:

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).

(Requires PHP on PATH: to invoke Composer).

We provide a Composer self-installer for Windows and UNIX. Invoke with:

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.

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

Step 1. Register on Sandbox

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

Grab a Private API token.

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

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

Invocation

(Requires phpunit on PATH).

To run all tests, cd to the repository root and invoke:

phpunit will read phpunit.xml to find tests and find which classes to autoload.

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

Run individual file

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

Or just invoke normally from anywhere using the terminal:

As with the full run, phpunit will climb the project structure looking for phpunit.xml.

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.

Specifically, cd into /build and invoke:

The newly-generated BillForward.php should be part of any commit.

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.

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.

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).

New major version:

Same major version:

Untag latest release: