Use AgileZen em PHP com ZF2

Recentemente, a equipe do Zend Framework começou a usar o sistema Kanban de AgileZen para gerenciar o projeto ZF2. Com o objetivo de comunicar, em tempo real, todas as fases de desenvolvimento do Zend Framework 2, construímos, no site do Zend Framework, uma página de bordo dev que lê o conteúdo da borda AgileZen usando a API REST desse serviço (ver figura abaixo).

Implementamos um componente de serviço, o Zend\Service\AgileZen, para facilitar o uso de API do AgileZen.

Neste artigo, eu gostaria de introduzir o uso do componente Zend\Service\AgileZen para entender como usar a API de AgileZen em PHP.

O que é AgileZen?

O AgileZen é uma ferramenta on-line de gerenciamento de projetos. Ele organiza seu projeto visual, permitindo-lhe ver a imagem grande, enquanto a ferramenta de gerenciamento de projeto mantém seu foco nas tarefas manuais. Se você está em uma equipe ou um trabalho solo, o AgileZen ajuda o gerenciamento de projetos se tornar mais organizado e eficiente, empregando estratégias das metodologias lean, agile e kanban. O AgileZen ajuda a compreender como você está indo com gerenciamento de projetos ágeis; e ele pode ser personalizado a medida que você encontrar melhores formas de trabalhar.

Zend\Service\AgileZen

Nós lançamos o componente Zend\Service\AgileZen na versão beta 3 do Zend Framework 2. Você pode encontrá-lo aqui.

Para usar este componente, você tem duas opções:

Baixar toda a biblioteca Zend Framework 2.0.0beta3;
Utilizar pyrus para instalar somente o componente Zend\Service\AgileZen (com todas as dependências).

A primeira opção é simples, então vamos discutir como usar a segunda. Eu suponho que você esteja usando uma caixa de GNU/Linux (se não, você tem que traduzir apenas os comandos do sistema operacional, a sintaxe pyrus é multi-plataforma).

Para utilizar pyrus, temos que instalá-lo. Você pode baixar aqui o pacote pyrus.phar no site da ZF. É possível usar o wget para baixar o pacote a partir da linha de comando:

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

Agora, podemos adicionar o repositório Zend Framework usando o seguinte comando:

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

Finalmente podemos instalar o componente Zend\Service\AgileZen com o comando:

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

O Pyrus irá instalar o componente Zend\Service\AgileZen na subpasta php. Nela você encontrará também outros componentes usados pelo serviço AgileZen (as classes de dependência).

A arquitetura do Zend\Service\AgileZen

O componente AgileZen do Zend Framework 2 é uma implementação orientada a objetos da API do AgileZen. Isso significa que temos as seguintes classes:

Zend\Service\AgileZen\Resources\Attachment;
Zend\Service\AgileZen\Resources\Comment;
Zend\Service\AgileZen\Resources\Invite;
Zend\Service\AgileZen\Resources\Phase;
Zend\Service\AgileZen\Resources\Project;
Zend\Service\AgileZen\Resources\Role;
Zend\Service\AgileZen\Resources\Story;
Zend\Service\AgileZen\Resources\Tag;
Zend\Service\AgileZen\Resources\Task;
Zend\Service\AgileZen\Resources\User;
Zend\Service\AgileZen\AgileZen;
Zend\Service\AgileZen\Container;
Zend\Service\AgileZen\Entity.

A Zend\Service\AgileZen\AgileZen é a classe principal que você tem que instanciar para chamar a API do AgileZen. Os resultados da API normalmente são “Resources”. Os “Resources” são organizados em dois tipos básicos: os de entidade (Entity) e de contêineres (Container). Um recurso entidade refere-se a uma única peça de informação em AgileZen, como um projeto ou uma história. Um recurso de contêiner refere-se a um recurso que contém um ou mais recursos de entidades, como a lista de histórias em um projeto ou a lista de tags atribuídas a uma história.

Seguimos a convenção de nomenclatura relatada na documentação da API AgileZen. A Entiy[ty é uma classe abstrata e o “Resources” (Comentário Anexo, Convidar, Fase, Projeto, Papel, História, Tag, Tarefa, Usuário) são as implementações concretas. O Container é uma classe que implementa uma série de entidades, implementando as interfaces de PHP Contábeis, Iterator e ArrayAccess.

Como utilizar o serviço

Abaixo são apresentados alguns exemplos de como usar o componente Zend\Service\AgileZen. Para utilizar a classe ZF AgileZen, você tem que configurar o autoload das classes. Por exemplo, o exemplo seguinte mostra como utilizar o autoloader padrão de ZF2 (PSR-0 padrão).

// 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();

Com o autoloader no lugar, podemos começar a usar o serviço AgileZen.

Liste todos os projetos de uma conta

Este é um exemplo para recuperar todos os nomes de projetos de uma conta de AgileZen específica.

use Zend\Service\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";
}

Para executar este código de exemplo, você tem que inserir a sua chave de API de AgileZen. Essa chave pode ser gerada em Menu> Configurações> Desenvolvedor dos backend AgileZen.

A gestão de erro das chamadas de API é fornecida usando o método isSuccessful(), que retorna true se a operação for realizado com sucesso, ou false, caso contrário. Se tivermos um, erro nós podemos usar getErrorCode() ou getErrorMsg() para obter o código de erro (o código de status HTTP) e a mensagem de erro.

Os resultados da chamada getProject() é uma instância de Container que contém uma matriz de objetos Recursos\Projeto.

Podemos repetir no objeto Container ($projectos) para obter o nome de cada projeto, utilizando o método getName().

Obter todas as fases e histórias de um projeto

Neste exemplo, vamos mostrar como obter todas as fases e histórias de um projeto AgileZen específico.

use Zend\Service\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): %s\n", $phase->getId(), $phase->getName());
    $stories = $phase->getStories();
    if ($agileZen->isSuccessful()) {
        foreach ($stories as $story) {
            printf ("Story (%d): %s\n", $story->getId(), $story->getText());
        }
    } else {
        printf ("Error reading the stories, %s", $agileZen->getErrorMsg()); 
    }  
    echo "\n";
}

Veja todos os detalhes e tags de uma história

Se você quiser recuperar os detalhes e as tags de uma história, você tem que especificar parâmetros adicionais. Estes parâmetros são chamados de enriquecimentos na terminologia API AgileZend (ver aqui para mais detalhes).

No exemplo abaixo, podemos recuperar todo o ID, o nome, detalhe e tags de cada história de todas as fases de um projeto.

use Zend\Service\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): %s\n", $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): %s\n", $story->getId(), $story->getText());
            printf ("Details : %s\n", $story->getDetails());
            printf ("Tags : %s\n", $tags);
        }
    } else {
        printf ("Error reading the stories, %s", $agileZen->getErrorMsg()); 
    }  
    echo "\n";
}

Os parâmetros de enriquecimento são passados ??como matriz para o método getStories ($ params). A chave e o valor destes parâmetros seguem a especificação da API AgileZend. Os parâmetros também podem incluir opções de filtro e paginação de AgileZen. Por exemplo, se você quiser filtrar as histórias que contêm a tag ‘foo’, você pode usar o parâmetro:

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

nas chamada getStories ($ params). Na sintaxe do filtro, onde você pode especificar múltiplas condições utilizando operadores lógicos (e, ou, não). Por exemplo, você pode especificar um filtro para obter todas as histórias com a tag ‘foo’ e status “bloqueado” com a seguinte sintaxe:

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

Se você quiser limitar o tamanho do resultado, você pode usar o parâmetro de paginação. A paginação contém a página principal e pageSize. Por padrão, você receberá a primeira página de 100 entidades no container. Para solicitar a página seguinte, você pode fornecer o argumento de página. Você também pode alterar o tamanho da página usando o parâmetro pageSize (max = 1000).

Conclusão

Neste artigo eu mostrei como utilizar a API AgileZen em PHP, usando um componente de serviço de Zend Framework 2 (Zend\Service\AgileZen). Explorei apenas um subconjunto de todas as funcionalidades do componente AgileZen. O guia de referência completo do componente de serviço AgileZen, como parte do manual ZF2, ainda está em desenvolvimento. É preciso lembrar que o Zend Framework 2 foi lançado como uma versão beta. A API do AgileZen ainda está em versão beta também. Essas versões não são destinadas para uso em produção, por favor, use por seu próprio risco.

***

Texto original disponível em: http://www.zimuel.it/en/agilezen-with-zend-framework-2/

De 0 a 10, o quanto você recomendaria este artigo para um amigo?

Powered by: