teamzac/openzac-api-php

Official PHP API client for openzac.com

OpenZac API PHP Client

This is the PHP client for the OpenZac API., _(*1)

Getting Started

You'll need an API key. Get one at https://openzac.com., _(*2)

Creating an instance of the client

$apiToken = 'YOUR_TOKEN';
$client = new TeamZac\OpenZac\OpenZac($apiToken);

In Laravel

Include the service provider in your config/app.php file:, _(*3)

TeamZac\OpenZac\OpenZacServiceProvider::class,

Publish the package's config file:, _(*4)

$ php artisan vendor:publish --provider="TeamZac\OpenZac\OpenZacServiceProvider"

Add your API token, preferably to your .env file:, _(*5)

OPENZAC_API_TOKEN=YOUR_TOKEN

Or set it directly in the config file:, _(*6)

'token' => 'YOUR_TOKEN'

The service provider binds a singleton instance of TeamZac\OpenZac\OpenZac to the IoC container, which you can access using the key 'OpenZac':, _(*7)

app('OpenZac');

Using the client

The remainder of the documentation will assume you're using Laravel. If not, you can replace app('OpenZac) with a normal instance of TeamZac\OpenZac\OpenZac., _(*8)

We're fleshing out a fluent interface to the API, but for now you can just use the get() method on the client, providing a URI path and optionally any parameters or headers you wish to pass along:, _(*9)

app('OpenZac')->get('entities/austin-texas');

app('OpenZac')->get('sales-tax/collections/2016/11', [
    'page' => 2,
    'take' => 25
]);

Retreiving Entities

We do have a minimally developed interface for accessing 'entity' resources. You can access this interface using the entities attribute on the OpenZac instance:, _(*10)

app('OpenZac')->entities;

There are two public methods on this resource: all() and find()., _(*11)

all()

app('OpenZac')->entities->all() is the same as calling get('entities'). You can pass an array of query parameters as the lone argument:, _(*12)

app('OpenZac')->entities->all(['page' => 3]);

find()

The find() method takes an entity ID as its lone parameter, and will retrieve a single entity record., _(*13)

app('OpenZac')->entities->find('austin-texas');

Resources and Collections

API calls return either an instance of TeamZac\OpenZac\Support\Resource or TeamZac\OpenZac\Support\ResourceCollection., _(*14)

TeamZac\OpenZac\Support\Resource

Right now this is just a simple wrapper for the response which allows you to access data as properties on the Resource object., _(*15)

$austin = app('OpenZac')->entities->find('austin-texas');
$austin->name;
// prints 'Austin'

The infrastructure is in place to provide more helpful functionality by using this as a base class. Future development plans include each resource having it's own subclass. This will allow for casting attributes to certain data types and potentially other valuable features., _(*16)

TeamZac\OpenZac\Support\ResourceCollection

This is a simple wrapper around responses that return more than a single resource. It has a couple of public methods which may be useful:, _(*17)

data() returns the resources, which are subclasses of TeamZac\OpenZac\Support\Resource., _(*18)

meta() returns any metadata associated with the response. Typically this will just be information related to pagination where applicable., _(*19)

nextPage() returns the next page number or null if it does not exist., _(*20)

previousPage() returns the previous page number or null if it does not exist., _(*21)