Jirabundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require alpixel/jirabundle
   

   (Note: This package is designed for Symfony 2.x, so ensure your project is compatible.)

2. Register the Bundle in app/AppKernel.php:

   public function registerBundles()
   {
       $bundles = [
           // ...
           new Alpixel\Bundle\JiraBundle\AlpixelJiraBundle(),
       ];
   }
   

3. Configure the Bundle in app/config/config.yml:

   alpixel_jira:
       base_url: 'https://your-domain.atlassian.net/rest/api/2/'  # Replace with your Jira URL
       auth:
           method:
               basic:
                   username: 'your-email@example.com'  # Jira email
                   password: 'your-api-token'         # Use an API token, not password
   

   (Generate an API token in Jira: Profile → Security → API Tokens.)

4. First Use Case: Fetch a simple endpoint (e.g., user info) in a controller:

   use Symfony\Component\HttpFoundation\Response;
   
   class JiraController extends Controller
   {
       public function userInfoAction()
       {
           $jira = $this->get('alpixel_jira.api');
           $response = $jira->get('/myprefix/currentuser');
           $data = $response->getData();
   
           return new Response(json_encode($data));
       }
   }
   

Implementation Patterns

Core Workflows

1. Basic API Calls: Use the service alpixel_jira.api for HTTP requests:

   $jira = $this->get('alpixel_jira.api');
   $response = $jira->get('/issue/{issueKey}');  // GET request
   $response = $jira->post('/issue', ['fields' => [...]]);  // POST request
   

2. JQL Searches: Query issues with Jira Query Language (JQL):

   $response = $jira->search(
       '(project = "PROJ" AND status = "Open")',
       ['maxResults' => 50, 'fields' => ['summary', 'assignee']]
   );
   $issues = $response->getData()['issues'];
   

3. Response Handling: The Response object provides methods like:

   • getData(): Raw decoded response.
   • getStatusCode(): HTTP status code.
   • getHeaders(): Response headers.

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

   try {
       $response = $jira->get('/invalid-endpoint');
   } catch (\RuntimeException $e) {
       // Handle Jira API errors (e.g., 404, 403)
       $this->addFlash('error', $e->getMessage());
   }
   

Integration Tips

• Dependency Injection: Inject the service directly into controllers/services:

  use Alpixel\Bundle\JiraBundle\Service\JiraApi;
  
  class MyService
  {
      private $jira;
  
      public function __construct(JiraApi $jira)
      {
          $this->jira = $jira;
      }
  }
  

• Configuration Overrides: Override config per environment (e.g., config_dev.yml):

  alpixel_jira:
      base_url: '%env(JIRA_BASE_URL)%'
  

• Rate Limiting: Jira has rate limits (e.g., 5000 requests/3 hours). Cache responses aggressively:

  $cache = $this->get('cache.app');
  $cacheKey = 'jira_issues_' . md5($jql);
  if (!$issues = $cache->get($cacheKey)) {
      $issues = $jira->search($jql)->getData();
      $cache->set($cacheKey, $issues, 3600); // Cache for 1 hour
  }
  

Gotchas and Tips

Pitfalls

1. Authentication:

   • Basic Auth Limitation: Only Basic Auth is supported. For OAuth or other methods, you’ll need to fork/modify the bundle.
   • API Tokens: Always use Jira API tokens instead of passwords for security.

2. Endpoint URLs:

   • The base_url must include /rest/api/2/ (e.g., https://example.atlassian.net/rest/api/2/). Missing this will cause 404 errors.
   • Use /myprefix/ for Cloud instances (replace myprefix with your Jira prefix).

3. Response Parsing:

   • The getData() method returns a decoded JSON array. Nested data (e.g., issues.fields) may require additional parsing:

     $summary = $issues['issues'][0]['fields']['summary'];
     

4. Pagination:

   • Search results are paginated. Use startAt and maxResults to navigate:

     $response = $jira->search($jql, ['startAt' => 50, 'maxResults' => 50]);
     

5. Symfony 2.x Legacy:

   • This bundle is not compatible with Symfony 3+ or 4+. Use alternatives like atlassian/jira-php for modern projects.

Debugging Tips

1. Enable Debug Mode: Add this to config.yml to log raw responses:

   alpixel_jira:
       debug: true
   

2. Check HTTP Status Codes: Inspect $response->getStatusCode() for issues (e.g., 403 = auth failure, 400 = invalid JQL).

3. Validate JQL: Test queries in Jira’s UI first (e.g., Issues → Search for Issues). Common mistakes:

   • Missing quotes around project keys ("PROJ" vs PROJ).
   • Case sensitivity in statuses (e.g., "Open" vs "open").

4. CORS Issues: If calling from a frontend, ensure your Jira instance allows CORS or use a backend proxy.

Extension Points

1. Custom Endpoints: Extend the JiraApi service by overriding the bundle’s compiler pass:

   # config.yml
   services:
       app.jira.api:
           class: App\Service\CustomJiraApi
           parent: alpixel_jira.api
           calls:
               - [setCustomEndpoint, ['/mycustom']]
   

2. Add OAuth Support: Fork the bundle and modify Alpixel\Bundle\JiraBundle\Service\JiraApi to support OAuth2 using league/oauth2-client.

3. Event Listeners: Listen for Jira webhooks by extending the bundle or using a separate service to validate signatures (e.g., atlassian-connect events).