README

Lumen/Laravel service provider for interacting with Zuora SOAP API

Install and configuration

You can install this package via Composer.

Direct usage (framework agnostic)

For using Zuora API you should register an account and get credentials for accessing an API. All credentials are passed into API::__construct method in array with structure:

[
    'wsdl'     => '/path/to/zuora.wsdl',
    'username' => 'user@example.com',
    'password' => 'very-good-password',
    'endpoint' => 'https://apisandbox.zuora.com/apps/services/a/74.0',
]

You can find sample config file in storage/config.dist.php

Lumen\Laravel Service Provider

Register ZuoraSdkServiceProvider in your app
Create a config file named zuora.php in config folder and put there contents of storage/config.dist.php
Have fun

Tests

This library is tested using PHPUnit and Mockery.

If you want to run full set of integration tests you should fill your storage/config.php file, which is excluded from source tree and copied automatically from config.dist.php with Composer's post-install-cmd. Otherwise all tests making real api calls will be skipped. Make sure you provided sandbox credentials!

Class Reference

All classes are located under Spira\ZuoraSdk namespace is omitted below.

API

This class:

Configures and stores \SoapClient, you can use getClient() and setClient(\SoapClient $client) methods for access
Performs lazy authorization on first request
Provides methods for operating with DataObject entites
Provides methods for selecting DataObject with ZOQL
Converts Zuora API Errors to thrown \Spira\ZuoraSdk\Exception\ApiException

Current list of implemented methods:

create($objects) - Create object in API. Accepts DataObject|DataObject[]
update($objects) - Update object in API. Accepts DataObject|DataObject[]
delete($type, $ids) - Delete objects of $type with IDs int|array $ids
query($query, $limit = null) - Runs a query and returns objects of type was queried.
queryMore($limit) - If resultset for query() has few pages use this method to get next pages of previous call.
hasMore() - Check does last query() has next page of resultset.

DataObject

DataObject is an object for storing data while operating with API.

It extends \Illuminate\Support\Fluent so all data manipulation is done easilly in array- or object-like syntax.

QueryBuilder

Zuora API provides ZOQL - simplified query language for querying objects from api.

QueryBuilder allows building such queries in fluent style:

$builder = new QueryBuilder('Products', ['Id', 'Name']);
$builder->where('Age', '=', $age)
    ->orWhere('Id', '=', $id);
echo $builder->toZoql(); // Output: SELECT Id, Name FROM Products WHERE Age = 18 OR Id = 1

Mostly it used for making queries in Zuora class described below.

Zuora

This class provides querying helpers and some part of common logic for using API.

getAll($table, array $columns, $limit = null, \Closure $filtered = null) - builds a query and returns an array of objects of type $table
getOne($table, array $columns, \Closure $filtered = null) - builds a query and returns one object of type $table
getOneById($table, $columns, $id) - pretty the same as getOne but with built-in filter by id.

Instance of QueryBuilder is passed into $filtered lambda for adding conditions to query if needed. While ZOQL does not support wildcards for columns you should provide list of them manually.

For some types of objects there are added custom methods:

Products

getAllProducts(array $columns = null, $limit = null, \Closure $filtered = null)
getOneProduct($id, array $columns = null)
getAllProductRatePlans(array $columns = null, $limit = null, \Closure $filtered = null)
getRatePlansForProduct($product, array $columns = null, $limit = null)
getOneProductRatePlan($id, array $columns = null)
getOneProductRatePlanActiveCurrencies($ratePlan)
getAllProductRatePlanCharges(array $columns = null, $limit = null, \Closure $filtered = null)
getChargesForProductRatePlan($ratePlan, array $columns = null, $limit = null)
getOneProductRatePlanCharge($id, array $columns = null)
getAllProductRatePlanChargeTiers(array $columns = null, $limit = null, \Closure $filtered = null)
getTiersForProductRatePlanCharge($ratePlanCharge, array $columns = null, $limit = null)
getOneProductRatePlanChargeTier($id, array $columns = null)

Accounts

getAllAccounts(array $columns = null, $limit = null, \Closure $filtered = null)
getOneAccount($id, array $columns = null)
getContactsForAccount($account, array $columns = null, $limit = null)
getOneContact($id, array $columns = null)
getPaymentMethodsForAccount($account, array $columns = null, $limit = null)
getOnePaymentMethod($id, array $columns = null)
getAllPaymentMethods(array $columns = null, $limit = null, \Closure $filtered = null)
createAccount(Account $account, Contact $contact, PaymentMethod $paymentMethod = null)

Subscriptions

getAllSubscriptions(array $columns = null, $limit = null, \Closure $filtered = null)
getOneSubscription($id, array $columns = null)
getSubscriptionsForAccount($account, array $columns = null, $limit = null)
subscribe(Account $account, Subscription $subscription, ProductRatePlan $ratePlan, ProductRatePlanCharge $ratePlanCharge = null, PaymentMethod $paymentMethod = null, Contact $contact = null, SubscribeOptions $subscribeOptions = null)

Payments & Invoices

getAllPayments(array $columns = null, $limit = null, \Closure $filtered = null)
getOnePayment($id, array $columns = null)
getPaymentsForAccount($account, array $columns = null, $limit = null)
getAllInvoices(array $columns = null, $limit = null, \Closure $filtered = null)
getOneInvoice($id, array $columns = null)
getInvoicesForAccount($account, array $columns = null, $limit = null)

Usage Example

use Monolog\Logger;
use Spira\ZuoraSdk\API;
use Spira\ZuoraSdk\Zuora;
use Monolog\Handler\StreamHandler;
use Spira\ZuoraSdk\DataObjects\Product;

$config = require '/path/to/config.php';
$logger = new Logger('zuora', [new StreamHandler('path/to/zuora.log')]); // optional logger usage
$api    = new API($config, $logger);
$zuora  = new Zuora($api);

// Create a new product

$product = new Product(['Name' => 'My Product']);
$api->create($product);

// Get list of a products

/** @var $products Product[] */
$products = $zuora->getAllProducts();

// Delete product

$api->delete('Product', [$product->Id]);

You can find more samples in tests.

Contribution

All commits MUST follow PSR-2 coding style guide.

You may use the PHP-CS-Fixer manually or use git pre-commit hook supplied in hooks/pre-commit. Follow instructions in file and make sure it is executable.

spira / zuora-laravel-sdk

Maintainers

Details