Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
php_pivotal_tracker_class [2011/10/22 02:16]
Joel Dare [Download]
php_pivotal_tracker_class [2011/10/22 02:20] (current)
Joel Dare [Requirements]
Line 1: Line 1:
 +====== 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.
 +
 +
 +===== 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. |
 +
 +Here's an example of how to add a story with a couple of tasks.
 +
 +<code php>
 +// Insert a new story
 +$story = $pivotal->​addStory('​chore',​ 'Clean the Kitchen',​ 'Need to deep clean the kitchen.'​);​
 +</​code>​
 +
 +===== Add a Task =====
 +
 +**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.
 +
 +<code php>
 +// 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'​);​
 +</​code>​
 +
 +===== Add Labels =====
 +
 +**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.
 +
 +<code php>
 +// 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'​);​
 +</​code>​
 +
 +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.
 +
 +  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.
 +===== 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.
 +
 +{{:​php:​php-pivotal-tracker-class.zip}}
 +
  
 

comments powered by Disqus
php_pivotal_tracker_class.txt ยท Last modified: 2011/10/22 02:20 by Joel Dare