Jira Cloud Restapi Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require lesstif/jira-cloud-restapi
   

   Register the service provider in config/app.php:

   'providers' => [
       // ...
       JiraCloud\JiraCloudApiServiceProvider::class,
   ],
   

2. Configuration:

   • Copy .env.example to .env and update:

     JIRAAPI_V3_HOST='https://your-jira.atlassian.net'
     JIRAAPI_V3_USER='jira-username'
     JIRAAPI_V3_PERSONAL_ACCESS_TOKEN='your-token-here'
     

   • Or configure via ArrayConfiguration in code.

3. First Use Case: Fetch a project's issues using JQL:

   use JiraCloud\Issue\IssueService;
   
   $issues = app(IssueService::class)->searchIssues('project = TEST ORDER BY created DESC');
   

Implementation Patterns

Core Workflows

1. Issue Management:

   • Create: Use IssueService::createIssue() with a JiraCloud\Issue\Issue object.

     $issue = (new Issue())
         ->setProjectKey('TEST')
         ->setSummary('Fix bug')
         ->setDescription('Detailed description');
     $created = $issueService->createIssue($issue);
     

   • Search: Leverage JQL for queries:

     $issues = $issueService->searchIssues('project = TEST AND status = "In Progress"');
     

   • Transitions: Use transitionIssue() with transition IDs:

     $issueService->transitionIssue($issueKey, $transitionId);
     

2. Project Operations:

   • CRUD: Use ProjectService for project lifecycle:

     $project = (new Project())
         ->setKey('NEW')
         ->setName('New Project');
     $projectService->createProject($project);
     

3. Bulk Operations:

   • Bulk Issues: Use createIssues() for multiple issues:

     $issueService->createIssues([$issue1, $issue2]);
     

4. Integration with Laravel:

   • Service Binding: Bind the service in a provider:

     $this->app->bind(IssueService::class, function ($app) {
         return new IssueService($app->make(JiraCloudConfiguration::class));
     });
     

   • Facade: Create a facade for cleaner syntax:

     // In a facade class
     public static function searchIssues($jql) {
         return app(IssueService::class)->searchIssues($jql);
     }
     

5. Event Listeners:

   • Webhooks: Use Laravel's HandleIncomingWebhook to process Jira webhook events:

     public function handleIncomingWebhook(Request $request) {
         $payload = $request->json()->all();
         // Process payload (e.g., update local DB)
     }
     

Gotchas and Tips

Pitfalls

1. Authentication:

   • Token Rotation: Personal access tokens expire. Cache tokens and implement refresh logic.
   • Cookie Auth: If using JIRAAPI_V3_COOKIE_AUTH_ENABLED, ensure the cookie file path is writable.

2. Rate Limiting:

   • Jira Cloud enforces rate limits (e.g., 100 requests/10 seconds). Implement exponential backoff for retries:

     try {
         $result = $service->someApiCall();
     } catch (RateLimitExceededException $e) {
         sleep(2); // Backoff
         retry();
     }
     

3. Pagination:

   • Always check for isLast in paginated responses to avoid missing data:

     $issues = $issueService->searchIssues('project = TEST');
     while (!$issues->isLast) {
         $issues = $issueService->searchIssues('project = TEST', $issues->startAt + $issues->maxResults);
     }
     

4. Field Validation:

   • Custom fields may require specific configurations. Use getAllFields() to inspect available fields:

     $fields = $issueService->getAllFields();
     

5. Error Handling:

   • Wrap API calls in try-catch blocks to handle JiraException:

     try {
         $issueService->createIssue($issue);
     } catch (JiraException $e) {
         Log::error('Jira API Error: ' . $e->getMessage());
         throw new \RuntimeException('Failed to create issue', 0, $e);
     }
     

Tips

1. Logging:

   • Enable logging via .env:

     JIRAAPI_V3_LOG_ENABLED=true
     JIRAAPI_V3_LOG_FILE=storage/logs/jira.log
     

   • Use Laravel's logging facade for structured logs:

     Log::debug('Jira API Response', ['data' => $response]);
     

2. Testing:

   • Mock the JiraCloudApiServiceProvider in tests:

     $this->app->instance(JiraCloudConfiguration::class, $mockConfig);
     

3. Performance:

   • Cache frequent queries (e.g., project lists) using Laravel's cache:

     $projects = Cache::remember('jira_projects', now()->addHours(1), function () {
         return $projectService->getAllProjects();
     });
     

4. Extensions:

   • Custom Services: Extend base services for domain-specific logic:

     class CustomIssueService extends IssueService {
         public function createBug($summary, $description) {
             $issue = (new Issue())
                 ->setProjectKey('BUG')
                 ->setSummary($summary)
                 ->setDescription($description)
                 ->setIssueType('Bug');
             return $this->createIssue($issue);
         }
     }
     

5. Proxy Support:

   • Configure proxy settings in .env if behind a corporate firewall:

     JIRAAPI_V3_PROXY_SERVER='proxy.example.com'
     JIRAAPI_V3_PROXY_PORT=8080
     

6. Webhook Validation:

   • Validate webhook payloads using Atlassian's public keys:

     $publicKey = 'your-atlassian-public-key';
     $signature = $request->header('X-Atlassian-Event-Key');
     $payload = $request->getContent();
     if (!hash_equals($signature, hash_hmac('sha1', $payload, $publicKey))) {
         abort(403, 'Invalid signature');
     }