Jira Rest Api Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require bluetea/jira-rest-api-bundle dev-master
   

   Add to AppKernel.php:

   new Bluetea\JiraRestApiBundle\BlueteaJiraRestApiBundle(),
   

2. Configure: Add to config.yml:

   bluetea_jira_rest_api:
       api_client: guzzle  # or 'http' (default)
       api:
           jira: "https://your-domain.atlassian.net/rest/api/2/"
       authentication:
           jira:
               type: basic
               username: "%env(JIRA_USERNAME)%"
               password: "%env(JIRA_API_TOKEN)%"
   

3. First Use Case: Inject the jira_rest_api.jira.endpoint.project service in a controller or service:

   use Symfony\Component\HttpFoundation\JsonResponse;
   
   public function listProjects()
   {
       $projects = $this->get('jira_rest_api.jira.endpoint.project')->findAll();
       return new JsonResponse($projects);
   }
   

Where to Look First

• Bundle Docs: GitHub README (limited but functional).
• Underlying Library: JIRA REST API PHP Library for advanced use cases.
• Service Tags: Check services.yml for tagged endpoints (e.g., jira_rest_api.jira.endpoint.*).

Implementation Patterns

Core Workflows

1. Dependency Injection: Use tagged services for endpoints (e.g., project, issue, user). Example:

   $issueEndpoint = $this->get('jira_rest_api.jira.endpoint.issue');
   $issues = $issueEndpoint->findAll(['jql' => 'project = TEST']);
   

2. Configuration-Driven: Extend config.yml for multiple JIRA instances:

   bluetea_jira_rest_api:
       api:
           jira_prod: "https://prod.atlassian.net/rest/api/2/"
           jira_staging: "https://staging.atlassian.net/rest/api/2/"
       authentication:
           jira_prod: { type: basic, username: "%env(JIRA_PROD_USER)%", password: "%env(JIRA_PROD_TOKEN)%" }
           jira_staging: { type: basic, username: "%env(JIRA_STAGING_USER)%", password: "%env(JIRA_STAGING_TOKEN)%" }
   

   Access via:

   $this->get('jira_rest_api.jira_prod.endpoint.project')->findAll();
   

3. Custom Endpoints: Extend the bundle to add missing endpoints (see underlying library for examples).

4. Error Handling: Wrap API calls in try-catch blocks:

   try {
       $issue = $issueEndpoint->get($issueId);
   } catch (\Bluetea\JiraRestApiBundle\Exception\JiraRestApiException $e) {
       $this->addFlash('error', $e->getMessage());
   }
   

Integration Tips

• Symfony Events: Trigger events on JIRA API responses (e.g., jira.api.response).
• Caching: Cache responses for read-heavy operations:

  $cache = $this->get('cache.app');
  $key = 'jira_projects_' . md5($jql);
  if (!$projects = $cache->get($key)) {
      $projects = $projectEndpoint->findAll(['jql' => $jql]);
      $cache->set($key, $projects, 3600);
  }
  

• Async Processing: Use Symfony’s Messenger component to queue JIRA API calls for background processing.

Gotchas and Tips

Pitfalls

1. Deprecated Bundle:

   • The bundle is archived and lacks maintenance. Use at your own risk.
   • Consider alternatives like atlassian-php-sdk or php-jira.

2. Authentication Quirks:

   • API Tokens: For JIRA Cloud, use API tokens instead of passwords.
   • Anonymous Mode: Limited functionality; use basic for most operations.

3. Rate Limiting:

   • JIRA Cloud enforces rate limits. Implement retries with exponential backoff:

     use Symfony\Component\HttpKernel\Exception\TooManyRequestsHttpException;
     
     try {
         $response = $endpoint->get($id);
     } catch (TooManyRequestsHttpException $e) {
         sleep(2 ** $retryCount); // Exponential backoff
         $retryCount++;
         retry();
     }
     

4. Endpoint Limitations:

   • Not all JIRA endpoints are exposed. For unsupported endpoints, use the underlying library directly:

     $client = $this->get('jira_rest_api.jira.client');
     $response = $client->get('/rest/api/2/serverInfo');
     

Debugging

1. Enable Debug Mode: Set debug: true in config.yml to log API requests/responses:

   bluetea_jira_rest_api:
       debug: true
   

2. Guzzle Debugging: If using Guzzle, enable middleware for debugging:

   $client = $this->get('jira_rest_api.jira.client');
   $client->getEmitter()->attach(
       new \GuzzleHttp\Middleware::tap(function ($request) {
           error_log($request->getUri());
       })
   );
   

3. Common Errors:

   • 403 Forbidden: Check credentials or API token permissions.
   • 404 Not Found: Verify endpoint URLs (e.g., /rest/api/2/ vs /rest/api/3/).
   • 500 Server Error: JIRA may be down; implement retry logic.

Extension Points

1. Custom Services: Create a custom service to extend functionality:

   # services.yml
   services:
       app.jira_custom_service:
           class: App\Service\JiraCustomService
           arguments:
               - '@jira_rest_api.jira.client'
           tags: ['jira.custom']
   

2. Override Configuration: Use parameters.yml to override default values:

   parameters:
       bluetea_jira_rest_api.api.jira: "https://custom-jira.atlassian.net/rest/api/2/"
   

3. Add New Endpoints: Extend the bundle by creating a custom endpoint service:

   // src/AppBundle/Service/JiraCustomEndpoint.php
   class JiraCustomEndpoint {
       private $client;
   
       public function __construct($client) {
           $this->client = $client;
       }
   
       public function customMethod() {
           return $this->client->get('/rest/custom/endpoint');
       }
   }
   

   Register in services.yml:

   services:
       app.jira.custom_endpoint:
           class: App\Service\JiraCustomEndpoint
           arguments: ['@jira_rest_api.jira.client']