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
$story | The story ID to pull. |
$project | The project ID. Defaults to the project ID set for the whole class. Optional. |
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
$type | The type of story to add (feature, bug, chore, or release). |
$name | The story name. |
$desc | The story description. |
$project | The project ID. Defaults to the project ID set for the whole class. Optional. |
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
$story | The ID of an existing story to modify . |
$task | The text of the task to create. |
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
$story | The ID of an existing story to modify . |
$labels | The text of the labels to add. |
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
$username | The username you have configured. |
$password | Your Pivotal Tracker password. |
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.