PHP Pivotal Tracker Class

This is a simple PHP class that connects to the Pivotal Tracker (pivotaltracker.com) API and lets you create a story in an existing project and assign tasks to that story. I wrote this because we switched to using Pivotal Tracker at work and I needed a way to insert stories from web based forms.

Here's an example of how to include the class and instantiate the object you'll use.

// Include the file that defines the class
require 'pivotal.php';
 
// Create an instance of the class
$pivotal = new pivotal;
 
// Set our API token and project number
$pivotal->token = 'your_token_goes_here';
$pivotal->project = 'your_project_goes_here';

Function

getStory($story, [$project]);

Options

Here's an example of how to get a story.

// Include the file that defines the class
require 'pivotal.php';
 
// Create an instance of the class
$pivotal = new pivotal;
 
// Set our API token and project number
$pivotal->token = 'your_token_goes_here';
$pivotal->project = 'your_project_goes_here';
 
// Get an existing story
$story = $pivotal->getStory('the_story_id');
 
// Display some details
echo $story->name;

Function

addStory($type, $name, $desc, [$project]);

Options

Here's an example of how to add a story with a couple of tasks.

// Insert a new story
$story = $pivotal->addStory('chore', 'Clean the Kitchen', 'Need to deep clean the kitchen.');

Function

addTask($story, $task);

Options

Here's an example of how to add a story with a couple of tasks.

// Insert a new story
$story = $pivotal->addStory('chore', 'Clean the Kitchen', 'Need to deep clean the kitchen.');
 
// Insert some tasks, using the story id returned
$pivotal->addTask($story->id, 'Wash the dishes');
$pivotal->addTask($story->id, 'Sweep the floor');

Function

addLabels($story, $labels);

Options

Here's an example of how to add a story with a label.

// Insert a new story
$story = $pivotal->addStory('chore', 'Clean the Kitchen', 'Need to deep clean the kitchen.');
 
// Insert some tasks, using the story id returned
$pivotal->addLabels($story->id, 'kitchen');

You can also include multiple labels by comma separating them, such as kitchen,clean,room.

Function

getToken($username, $password);

Options

Here's an example of how to get your token.

$pivotal->token = $pivotal->getToken('johndoe', 'abc123');

By default, Pivotal Tracker does not seem to set a username at all. In order to use the getToken() function you'll need to change your profile on pivotaltracker.com to have a username.

If you don't want your username and password stored in your script, you can also make a manual CURL call like the following. Replace $USERNAME and $PASSWORD with the same credentials you use to login to Pivotal Tracker.

curl -u $USERNAME:$PASSWORD -X GET https://www.pivotaltracker.com/services/v3/tokens/active

That will return a bit of XML data. In that you'll see a guid and an id. The guid is your token. I believe that it's permanent. You can then place that guid into your code and there is no need to call the getToken() function.

In most cases you also need to know your project ID. For that, just login to Pivotal Tracker, click on one of your projects, and take a look at the URL. It will look something like the following.

https://www.pivotaltracker.com/projects/123456

The number at the end is your project ID. In this case, 123456.

This script currently executes the command line version of CURL. In doing so it's using the PHP exec() command but it's also following Pivotal Tracker's own examples exactly. You'll need the CURL command line program installed on the server.

I'm currently storing this project on github. The latest files are always available from https://github.com/codazoda/PHP-Pivotal-Tracker-Class. You can also download my own zip file below, but I don't keep this file as current as the project on github.

php-pivotal-tracker-class.zip