This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
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}} | ||
+ | |||