PHP API Guide

PHP Integration

This document explains how to integrate with jBilling 2.x from PHP 5. It is assumed the reader has a basic working knowledge of object oriented programming with PHP.

Requirements

PHP 5.0+
PHP 5 Soap extension (http://www.php.net/soap)

“jbillingphpapi” Library

This library abstracts the Java based jBilling API, which in English, means one can follow along in the jBilling integration guide and all objects, methods, properties, and examples which are mentioned in regards to the Java API apply to the PHP library as well (except language specific eccentrics like the "->" operator instead of "." when working with object notation).

Download the jbillingphpapi from SourceForge: http://sourceforge.net/projects/jbillingphpapi/

The apidoc can be found online here: http://makeabyte.com/jbillingphpapi/apidoc/

Now we are ready to move onto the fun part—integrating your PHP application with jBilling!

Unit Testing

To use the testing package, install PHP Unit 3 via PEAR.

pear channel-discover pear.phpunit.de
pear install phpunit/PHPUnit

Now that phpunit is installed, navigate to the jbillingphpapi/test/mock directory and open MockConstants.php for edit. Next, you will want to modify the IDs to match the data in your jBilling database. When you are finished, move up a directory to the jbillingphpapi/test directory and then execute the file of choice. For example, to test the creation of a new user, use the following syntax:

phpunit CreateUserTest.php

Note: If you get stuck on any method calls, the test cases are a good place to start reverse engineering logic to figure out what you need to do to make your call work.

Integrating Your Application

Extract the jbillingphpapi archive to your project directory and open the project file responsible for integration with jBilling. We will use this project file to create a new customer account, credit card, and new purchase order.

Start by including jbillingphpapi/src/JbillingAPIFactory.php into your source file something like this:

require_once( "jbillingphpapi/src/JbillingAPIFactory.php" );

Once included, the JbillingAPIFactory is ready for use! Lets get started by creating a new API instance and then our new customer and purchase order…

$api = jBillingAPIFactory::getAPI( "http://localhost:8080/cxf/soap.service?wsdl", "admin", "123qwe", jBILLINGAPI_TYPE_CXF );

// Instantiate each of the required jBilling objects
$UserWS = new UserWS();
$OrderWS = new OrderWS();
$ContactWS = new ContactWS();
$OrderLineWS = new OrderLineWS();
$CreditCardDTO = new CreditCardDTO();

// Define jBilling user properties
$UserWS->setUserName( "PHP-TESTING" );
$UserWS->setPassword( "secret123" );
$UserWS->setLanguageId( 1 ); // English
$UserWS->setMainRoleId( 5 ); // Customer
$UserWS->setRole( "Customer" );
$UserWS->setStatusId( 1 ); // Active
$UserWS->setSubscriberStatusId( 1 ); // Pre-paid

// Define jBilling contact properties
$ContactWS->setFirstName( "PHP" );
$ContactWS->setLastName( "Testing" );
$ContactWS->setPhoneNumber( "123-456-7890" );
$ContactWS->setEmail( "[email protected]" );
$ContactWS->setAddress1( "123 Anywhere St" );
$ContactWS->setCity( "Some City" );
$ContactWS->setStateProvince( "Some State" );
$ContactWS->setPostalCode( "12345" );

// Apply contact object to user contact property
$UserWS->setContact( $ContactWS );

// Define jBilling credit card properties
$CreditCardDTO->setName( "PHP Testing" );
$CreditCardDTO->setNumber( "4012888888881881" );
$CreditCardDTO->setSecurityCode( 123 );
$CreditCardDTO->setType( 2 ); // Visa
// Define date as ISO 8601 format
$CreditCardDTO->setExpiry( date("c", strtotime( "now" ) ) );

// Add the credit card to the user credit card property
$UserWS->setCreditCard( $CreditCardDTO );

// Set jBilling OrderLineWS properties
$OrderLineWS->setUseItem( true );
$OrderLineWS->setItemId( 1 ); // MAKE SURE THIS ITEM MATCHES AN ITEM YOUR SYSTEM!
$OrderLineWS->setTypeId( 1 ); // Item
$OrderLineWS->setQuantity( 1 );
$OrderLineWS->setDescription( "test from php api" );

// Set jBilling purchase order properties
$OrderWS->setPeriod( 1 ); // Monthly
$OrderWS->setOrderLines( array( $OrderLineWS ) );
$OrderWS->setBillingTypeId( 1 );
$OrderWS->setCurrencyId( 1 ); // US Dollar
$OrderWS->getBillingTypeId( 1 ); // Pre-paid
$OrderWS->setUserId( 22 ); // Penny bright

// Attempt to create the new user and purcahse order
try {
print_r( $api->create( $UserWS, $OrderWS ) ); // New id's returned
//print_r( $api->createUser( $UserWS ) ); // New user id returned
//print_r( $api->createOrder( $OrderWS ) ); // New order id returned
//print_r( $api->getUserWS( 22 ) ); // User details for penny bright
}
catch( JbillingAPIFactory $e )

print_r( $e );
}

Now check the jBilling GUI to confirm the method invocation worked as intended. If not, you may want to check the jbilling_install_dir/logs directory for a Java exception stack that describes the issue in greater detail. If the call worked as intended, congratulations on your working API!

Developer Notes / Technical Details

Dates

When working with dates in PHP which are sent to the jBilling API, it is required to use the ISO 8601 format which is new to PHP 5.

Technical Notes

The jbillingphpapi is dependent upon PHP 5 and will not work in earlier versions.

Support

Support for this library can be obtained from the jBilling community, or commercial support is available from Make A Byte, Inc.

Conclusion

The jBillingphpapi library significantly eases the integration of jBilling into PHP applications. Using this library, PHP developers are able to overlook complicated SOAP formatting, serialization, and encoding issues, and focus their efforts on a successful jBilling integration.

About the Author

Jeremy Hahn is an active participant in the open source software movement and enjoys making his difference by contributing his various skills to communities as the opportunities arise. More of Jeremy's projects can be found at www.makeabyte.com.