Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
FreshBooks API Wrapper for CakePHP
branch: master

This branch is 2 commits behind shama:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
config
controllers
locale/eng/LC_MESSAGES
models
tests/cases/models
README.md
freshbooks_app_controller.php
freshbooks_app_model.php

README.md

FreshCake: A FreshBooks API Wrapper for CakePHP

Features

  • Automagically works with scaffolding!
  • Access the entire Freshbooks API!
  • Uses thrown exceptions for error handling.
  • Caching enabled to speed up and avoid your 5000 daily request limit!

Requirements

PHP5+, CakePHP 1.3+, FreshBooks account (w/ API credentials)

Installing

  1. Sign up for a FreshBooks account, they are free!
  2. Extract the contents of this repo into app/plugins/freshbooks/ or use git clone or git submodule in your plugins folder:

git clone git://github.com/shama/freshcake.git freshbooks

  1. Copy the following lines into app/config/database.php and add your subdomain and api token:

    var $freshbooks = array( 'datasource' => 'freshbooks.freshbooks', 'subdomain' => 'SUBDOMAIN-HERE', 'token' => 'TOKEN-HERE', );

Your subdomain is what you typed into the 'login page' field when you signed up or the word between http:// and .freshbooks.com in your login url.

Usage

Almost all of the API calls have find, save and delete capabilities. While this example is for the manipulating the client data the same techniques will work for the other API calls.

QUICK I NEED INSTA-AWESOME!

If you are lazy like myself just uncomment the var $scaffold; in the freshbooks_app_controller.php. Then type in http://yourwebsite.com/freshbooks/clients or http://yourwebsite.com/freshbooks/projects and so on. Cool eh?

Although you shouldn't do that: (1) because now your freshbooks account is opened to everyone and (2) you shouldn't modify the plugin (unless you are contributing!). Instead you should extend the plugin, more on that later.

CHOOSING A MODEL

In your controller, use the API just like you would any other model. Here we are going to use Client:

var $uses = array('Freshbooks.Client');

FIND ALL

To grab all records use (remember Freshbooks limits results to 100):

$clients = $this->Client->find('all');

FIND ONE

$client = $this->Client->find('first');

FIND BY USERNAME

$client = $this->Client->findByUsername('myusername');

OR

$client = $this->Client->find('all', array(
    'conditions' => array(
        'username' => 'myusername',
    ),
));

Each API has it restrictions on which fields you can find by. Please check the 'list' section of the FreshBooks API to see what fields are available to search by.

FIND AND LIMIT RESULTS (YES IT PAGINATES!)

$client = $this->Client->find('all', array(
    'limit' => 15,
    'page' => 2,
));

SAVE

$this->Client->save(array(
    'first_name' => 'Test',
    'last_name' => 'Person',
    'organization' => 'Test Inc.',
    'email' => 'test@example.com',
));

UPDATE

$this->Client->id = 13;
$this->Client->save(array(
    'first_name' => 'Test',
    'last_name' => 'Person',
    'organization' => 'Test Inc.',
    'email' => 'test@example.com',
));

OR

$this->Client->save(array(
    'client_id' => 13,
    'first_name' => 'Test',
    'last_name' => 'Person',
    'organization' => 'Test Inc.',
    'email' => 'test@example.com',
));

Please check the FreshBooks API for available fields to save and which are required (although this plugin does its best to validate!)

DELETE

$this->Client->delete(13);

ERROR HANDLING

It is highly recommended that you put a try catch statement around your code. Any errors returned from the API or this plugin will throw an error for you to deal with. Here is an example:

try {
    $clients = $this->Client->find('all');
} catch (Exception $e) {
    debug($e->getMessage());
}

EXTENDING THE MODELS

Please avoid modifying the plugin source code (unless you are contributing!). Here is how to extend and modify the models:

Create your own model in app/models/ lets call it my_client.php

App::import('Model', 'Freshbooks.Client');
class MyClient extends Client {
    var $name = 'MyClient';
}

Now you are free to extend the model however you like without editing the plugin!

OTHER METHODS

Take a look into each app/plugins/freshbooks/models/ to see other methods this plugin supports. For examples look in app/plugins/freshbooks/tests/cases/models/.

Issues

Please report any issues you have with the plugin to the issue tracker on github. This is a beta release so please be gentle!

License

FreshCake is offered under an MIT license.

Copyright

2010 Kyle Robinson Young, kyletyoung.com If you found this release useful please let the author know! Follow on Twitter

Roadmap and Known Issues

  • MORE TESTING! MORE TESTS!
  • Fix issue with some text fields showing up as Array - v0.2
  • Format lines/xml on invoice, estimate and recurring afterFind (so they dont break scaffold) - v0.2
  • Implement OAuth support - v0.3
  • i18n - v0.3
  • Smart Caching: If models have a relation then perform a 'list' call and cache it first. This will hit the freshbooks api less and speed up performance.

Changelog

0.2

  • Added support for invoice/recurring.lines.add/delete/update
  • Added support for project.hour_budget
  • Implemented caching on read with per model cache override option
  • Fixed formatting issues with responses
  • Implemented system.current and added test case
  • Implemented staff.current and fixed response from staff.list
  • Implemented recurring autobill and added test cases
  • Added invoice.sendByEmail and invoice.sendBySnailMail and test cases
  • Added estimate.sendByEmail and test case
  • Fields can be set to custom XML now (needed for fixing tasks in project)
  • Added test cases for callback.verify, callback.resendToken
  • Added support for callback.verify, callback.resendToken
  • Added methods to return last request and response xml
  • Built a better method for sending xml directly to freshbooks
  • Added test case for expense, invoice, item, payment, project, recurring, staff, task, time_entry models
  • Added test case for category, client, gateway, estimate models
  • Added support for project tasks
  • Added custom XML override to datasource
  • Added support for invoice and estimate lines

0.1

  • Added schema and validation for models
  • Added folder structure for i18n and tests
  • Added controllers for most api calls
  • Added models for each api call
  • Added freshbooks datasource to handle most of the API
  • Setup app model and app controller
  • Setup basic plugin
Something went wrong with that request. Please try again.