AgileZen with ZF2

How to integrate Project Management in PHP Posted by on March 08, 2012

Recently the Zend Framework team has started to use the Kanban system of AgileZen to manage the ZF2 project. In order to communicate, in real time, all the development phases of Zend Framework 2, we built a dev board page, in the Zend Framework web site, that reads the content of the AgileZen board using the REST API of that service.

We implemented a service component, ZendServiceAgileZen to facilitate the usage of the AgileZen's API.

In this post I would like to introduce the usage of the ZendServiceAgileZen component to understand how to use the API of AgileZen in PHP.

What's AgileZen?

AgileZen is an on-line project management tool. AgileZen organizes your project visually, letting you see the big picture, while the project management tool keeps you focused on the tasks at hand. Whether you're on a team or flying solo, AgileZen helps your project management become more organized and efficient by employing strategies from lean, agile, and kanban methodologies. AgileZen helps you understand how well you're doing with agile project management, and can be customized as you find better ways to work.

ZendServiceAgileZen

We released the ZendServiceAgileZen component in the beta3 version of Zend Framework 2, you can find it here: http://packages.zendframework.com/. In order to use this component you have two options:

  1. download the entire Zend Framework 2.0.0beta3 library;
  2. use pyrus to install only the ZendServiceAgileZen component (with all the dependencies).

The first option is straightforward, so we are going to discuss how to use the second one. I assume that you are using a GNU/Linux box (if not, you have to translate only the os commands, the pyrus syntax is multi-platform).
In order to use pyrus we have to install it. You can download here the pyrus.phar package from the ZF website. You can use wget to download the package from the command line:

$ mkdir AgileZen
$ cd AgileZen
$ wget http://packages.zendframework.com/pyrus.phar
$ chmod +x pyrus.phar

Now we can add the Zend Framework repository using the following command:

$ ./pyrus.phar . channel-discover packages.zendframework.com

Finally we can install the ZendServiceAgileZen component with the command:

$ ./pyrus.phar . install zf2/Zend_Service_AgileZen-beta

Pyrus will install the ZendServiceAgileZen component in the php subfolder. In that folder you will find also other components used by the AgileZen service (the dependency classes).

The architecture of ZendServiceAgileZen

The AgileZen component of Zend Framework 2 is an object oriented implementation of the AgileZen's API. That means we have the following classes:

  • ZendService\AgileZen\Resources\Attachment
  • ZendService\AgileZen\Resources\Comment
  • ZendService\AgileZen\Resources\Invite
  • ZendService\AgileZen\Resources\Phase
  • ZendService\AgileZen\Resources\Project
  • ZendService\AgileZen\Resources\Role
  • ZendService\AgileZen\Resources\Story
  • ZendService\AgileZen\Resources\Tag
  • ZendService\AgileZen\Resources\Task
  • ZendService\AgileZen\Resources\User
  • ZendService\AgileZen\AgileZen
  • ZendService\AgileZen\Container
  • ZendService\AgileZen\Entity

The ZendServiceAgileZenAgileZen is the main class that you have to instantiate to call the AgileZen's API. The results of the API are tipically Resources. Resources are organized into two basic types: entity resources (Entity) and container resources (Container). An entity resource refers to a single piece of information in AgileZen, like a project or a story. A container resource refers to a resource that contains one or more entity resources, like the list of stories in a project or the list of tags assigned to a story. We followed the naming convention reported in the AgileZen API documentation. The Entity is an abstract class and the Resources (Attachment, Comment, Invite, Phase, Project, Role, Story, Tag, Task, User) are the concrete implementations. The Container is a class that implements an array of entities, implementing the PHP interfaces Countable, Iterator and ArrayAccess.

How to use the service

Below are reported some examples of how to use the ZendServiceAgileZen component. In order to use the ZF AgileZen class you have to configure the autoload of the classes. For instance, in the following example we show how to use the standard autoloader of ZF2 (PSR-0 standard).

// if you used the pyrus installation, point to the php subfolder
require_once '/path to ZF2 library/Zend/Loader/StandardAutoloader.php';
$loader = new Zend\Loader\StandardAutoloader(array(
    'Zend' => '/path to ZF2 library/Zend/',
));
$loader->register();

With the autoloader in place we can start to use the AgileZen service.

- List all the projects of an account

This is an example to retrieve all the project names of a specific AgileZen account.

use ZendService\AgileZen\AgileZen;

$apiKey='insert here the API key';
$agileZen = new AgileZen($apiKey);

$projects = $agileZen->getProjects();
if (!$agileZen->isSuccessful()) {
    die("Error code    : " . $agileZen->getErrorCode() .
        "nError message : " . $agileZen->getErrorMsg());
}

echo "List of projects in AgileZen:n";
foreach ($projects as $prj) {
    echo $prj->getName(). "n";
}

In order to execute this example code you have to insert your API key of AgileZen. This key can be generated in the Settings > Developer menu of the AgileZen backend. The error management of the API calls is provided using the isSuccessful() method that returns true if the operation was successfully, false otherwise. If we have an error we can use getErrorCode() or getErrorMsg() to retrieve the error code (the HTTP status code) and the error message.
The results of the getProject() call is an instance of Container contains an array of ResourceProject objects. We can iterate on the Container object ($projects) to get the name of each project, using the getName() method.

- Get all the phases and stories of a project

In this example we show how to get all the phases and stories of a specific AgileZen project.

use ZendService\AgileZen\AgileZen;

$apiKey='insert here the API key';
$agileZen = new AgileZen($apiKey);

$phases = $agileZen->getPhases('insert here the Id of the project');
if (!$agileZen->isSuccessful()) {
    die ('Error: ' . $agileZen->getErrorMsg());
}

foreach ($phases as $phase) {
    printf ("Phase (%d): %sn", $phase->getId(), $phase->getName());
    $stories = $phase->getStories();
    if ($agileZen->isSuccessful()) {
        foreach ($stories as $story) {
            printf ("Story (%d): %sn", $story->getId(), $story->getText());
        }
    } else {
        printf ("Error reading the stories, %s", $agileZen->getErrorMsg());
    }
    echo "n";
}

- Get all the details and tags of a story

If you want to retrieve the details and the tags of a story you have to specify additional parameters. These parameters are called enrichments in the AgileZend API terminology (see here for more details).
In the example below we retrieve all the id, name, detail and tags of each story of all the phases of a project.

use ZendService\AgileZen\AgileZen;
$apiKey='insert here the API key';
$agileZen = new AgileZen($apiKey);

$phases = $agileZen->getPhases('insert here the Id of the project');
if (!$agileZen->isSuccessful()) {
    die ('Error: ' . $agileZen->getErrorMsg());
}

foreach ($phases as $phase) {
    printf ("Phase (%d): %sn", $phase->getId(), $phase->getName());
    $params = array (
        'with' => 'details,tags'
    );
    $stories = $phase->getStories($params);
    if ($agileZen->isSuccessful()) {
        foreach ($stories as $story) {
            $tags = '';
            foreach ($story->getTags() as $tag) {
                $tags.= $tag->getName() . ', ';
            }
            $tags = substr($tags,0,-2);
            printf ("Story (%d): %sn", $story->getId(), $story->getText());
            printf ("Details : %sn", $story->getDetails());
            printf ("Tags : %sn", $tags);
        }
    } else {
        printf ("Error reading the stories, %s", $agileZen->getErrorMsg());
    }
    echo "n";
}

The enrichment parameters are passed as array to the getStories($params) method. The key and the value of this parameters follow the specification of the AgileZend API. The parameters can also include Filter and Pagination options of AgileZen. For instance, if you want to filter the stories that contain the tag 'foo', you can use the parameter:

$params = array (
        'where' => 'tag:foo'
);

in the getStories($params) call. In the where filter syntax you can specify multiple conditions using logical operators (and, or, not). For instance, you can specify a filter to get all the stories with tag 'foo' and status 'blocked' with the following syntax:

$params = array (
        'where' => '(tag:foo and status:blocked)'
);

If you want to limit the size of the result you can use the pagination parameter. The pagination contains the key page and pageSize. By default, you will receive the first page of 100 entities in the container. To request the next page, you can supply the page argument. You can also change the size of the page using the pageSize parameter (max=1000).

Conclusion

In this post I showed hot to use AgileZen API in PHP using a service component of Zend Framework 2 (ZendServiceAgileZen). I explored only a subset of all functionalities of the AgileZen component. The complete reference guide of the AgileZen service component, as part of the ZF2 manual, is still in development. I have to remember that Zend Framework 2 is released as a beta and also the API of AgileZen are still in beta. These releases are not intended for production use, please use at your own risk.