Download the PHP package amcintosh/freshbooks without Composer

FreshBooks PHP SDK

A FreshBooks PHP SDK to allow you to more easily utilize the FreshBooks API. This library is not directly maintained by FreshBooks and community contributions are welcome.

Installation

Install it via Composer.

Requires a PSR-18 implementation client. If you do not already have a compatible client, you can install one with it.

Usage

See the full documentation or check out some examples.

This SDK makes use of the spryker/decimal-object package. All monetary amounts are represented as as Spryker\DecimalObject\Decimal, so it is recommended that you refer to their documentation.

Configuring the API client

You can create an instance of the API client in one of two ways:

• By providing your application's OAuth2 clientId and clientSecret and following through the auth flow, which when complete will return an access token.
• Or if you already have a valid access token, you can instantiate the client with that token, however token refresh flows will not function without the application id and secret.

and then proceed with the auth flow (see below).

Or

Authoization flow

This is a brief summary of the OAuth2 authorization flow and the methods in the FreshBooks API Client around them. See the FreshBooks API - Authentication documentation.

First, instantiate your Client with clientId, clientSecret, and redirectUri as above.

To get an access token, the user must first authorize your application. This can be done by sending the user to the FreshBooks authorization page. Once the user has clicked accept there, they will be redirected to your redirectUri with an access grant code. The authorization URL can be obtained by calling $freshBooksClient->getAuthRequestUri(). This method also accepts a list of scopes that you wish the user to authorize your application for.

Once the user has been redirected to your redirectUri and you have obtained the access grant code, you can exchange that code for a valid access token.

This call both sets the accessToken, refreshToken, and tokenExpiresAt fields on you Client's FreshBooksClientConfig instance and returns those values.

When the token expires, it can be refreshed with the refreshToken value in the FreshBooksClient:

or you can pass the refresh token yourself:

Current User

FreshBooks users are uniquely identified by their email across the entire product. One user may act on several Businesses in different ways, and the Identity model is how to keep track of it. Each unique user has an Identity, and each Identity has Business Memberships which define the permissions they have.

See FreshBooks API - Business, Roles, and Identity and FreshBooks API - The Identity Model.

The current user can be accessed by:

Making API Calls

Each resource in the client has provides calls for get, list, create, update and delete calls. Please note that some API resources are scoped to a FreshBooks accountId while others are scoped to a businessId. In general these fall along the lines of accounting resources vs projects/time tracking resources, but that is not precise.

Get and List

API calls which return a single resource return a DataTransferObject with the returned data accessible via properties.

visState numbers correspond with various states. See FreshBooks API - Active and Deleted Objects for details.

API calls which return a list of resources return a DataTransferObject with an array of the resources.

Create, Update, and Delete

API calls to create and update take either a DataModel object, or an array of the resource data. A successful call will return a DataTransferObject object as if a get call.

Note: When using the array of data, you need to specify the field as it exists in the FreshBooks API. There are API fields that are translated to more intuitive names in the data models. For example fname = firstName, or bus_phone = businessPhone.

Create:

or

Update:

or

Delete:

Error Handling

Calls made to the FreshBooks API with a non-2xx response are wrapped in a FreshBooksException. This exception class contains the error message, HTTP response code, FreshBooks-specific error number if one exists, and the HTTP response body.

Example:

TODO: this Not all resources have full CRUD methods available. For example expense categories have list and get calls, but are not deletable. If you attempt to call a method that does not exist, the SDK will raise a FreshBooksNotImplementedError exception, but this is not something you will likely have to account for outside of development.

Pagination, Filters, and Includes

list calls take a list of builder objects that can be used to paginate, filter, and include optional data in the response. See FreshBooks API - Parameters documentation.

Pagination

Pagination results are included in list responses:

To make a paginated call, first create a PaginateBuilder that can be passed into the list method.

PaginateBuilder has chainable methods page and perPage to set the values.

Filters

To filter which results are return by list method calls, construct a FilterBuilder and pass that in the list of builders to the list method.

Filters can be built with the methods: equals, inList, like, between, boolean, and datetime which can be chained together.

Please see FreshBooks API - Active and Deleted Objects for details on filtering active, archived, and deleted resources.

Includes

To include additional relationships, sub-resources, or data in a response an IncludesBuilder can be constructed.

Which can then be passed into list or get calls:

Includes can also be passed into create and update calls to include the data in the response of the updated resource:

Sorting

To sort the results of a list call by supported fields (see the documentation for that resource) a SortBuilder can be used.

to sort by the invoice date in ascending order, or:

for descending order.

Development

Testing

To run all tests:

Run a specific test:

Documentations

You can generate the documentation via: