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.

+

+

+

===== Use the Class =====

+

+

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

+

+

<code php>

+

// 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';​

+

</​code>​

+

+

===== Get a Story =====

+

+

**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.

+

+

<code php>

+

// 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;​

+

</​code>​

+

+

===== Add a Story =====

+

+

**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. |

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

+

+

===== Get Token =====

+

+

**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.

+

+

<code php>

+

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

+

</​code>​

+

+

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.

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.

+

===== Get Your Project ID =====

+

+

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.

+

+

===== Requirements =====

+

+

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.

+

===== Download =====

+

+

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.