Differences

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

--- php_pivotal_tracker_class [2011/10/22 02:16]
Joel Dare [Download]
+++ php_pivotal_tracker_class [2020/06/01 22:53] (current)
@@ 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}}