Jira Rest Api Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require bluetea/jira-rest-api
   

   Ensure your Laravel project has guzzlehttp/guzzle or php-curl installed (required for HTTP clients).

2. First Connection:

   use Bluetea\Api\Authentication\BasicAuthentication;
   use Bluetea\Api\Client\GuzzleClient;
   
   $client = new GuzzleClient(
       'https://your-jira-instance/rest/api/2',
       new BasicAuthentication('email@example.com', 'api-token')
   );
   

   • Replace api-token with a Jira API token.
   • For Laravel, store credentials in .env and inject via a service container.

3. First Endpoint Call:

   use Bluetea\Jira\Endpoint\IssueEndpoint;
   
   $issueEndpoint = new IssueEndpoint($client);
   $issues = $issueEndpoint->findAll(['jql' => 'project = TEST']);
   return response()->json($issues);
   

   • Use the Jira/Endpoint namespace for available endpoints (e.g., ProjectEndpoint, UserEndpoint).

Where to Look First

• Endpoints: Browse src/Jira/Endpoint/ for pre-built endpoints (e.g., IssueEndpoint, CommentEndpoint).
• Jira REST API Docs: Reference Atlassian’s official docs for unsupported endpoints.
• Debugging: Use Jira’s REST Browser plugin to validate endpoints manually.

Implementation Patterns

Workflows

1. Service Layer Integration: Create a Laravel service to encapsulate Jira logic:

   namespace App\Services;
   
   use Bluetea\Api\Client\GuzzleClient;
   use Bluetea\Jira\Endpoint\IssueEndpoint;
   
   class JiraService {
       protected $issueEndpoint;
   
       public function __construct(GuzzleClient $client) {
           $this->issueEndpoint = new IssueEndpoint($client);
       }
   
       public function createIssue(array $issueData) {
           return $this->issueEndpoint->create($issueData);
       }
   }
   

   • Bind in AppServiceProvider:

     $this->app->bind(JiraService::class, function ($app) {
         $client = new GuzzleClient(
             config('services.jira.url'),
             new BasicAuthentication(
                 config('services.jira.email'),
                 config('services.jira.token')
             )
         );
         return new JiraService($client);
     });
     

2. Query Builder Pattern: Chain methods for complex queries:

   $issues = $issueEndpoint
       ->findAll(['jql' => 'project = TEST'])
       ->filter(fn($issue) => $issue['status']['name'] === 'In Progress')
       ->map(fn($issue) => $issue['key']);
   

3. Event-Driven Actions: Trigger Jira actions on Laravel events (e.g., create a Jira issue on OrderCreated):

   use App\Services\JiraService;
   
   Event::listen(OrderCreated::class, function ($order) {
       $jiraService = app(JiraService::class);
       $jiraService->createIssue([
           'project' => ['key' => 'PROJ'],
           'summary' => "New order #{$order->id}",
           'description' => $order->details,
       ]);
   });
   

Integration Tips

• Rate Limiting: Jira enforces rate limits. Cache responses aggressively:

  $cacheKey = 'jira_issues_' . md5($jql);
  return Cache::remember($cacheKey, now()->addMinutes(5), function () use ($issueEndpoint, $jql) {
      return $issueEndpoint->findAll(['jql' => $jql]);
  });
  

• Error Handling: Wrap calls in a try-catch to handle Jira-specific errors (e.g., 404 Not Found for invalid issues):

  try {
      $issue = $issueEndpoint->get('TEST-123');
  } catch (\Bluetea\Api\Exception\ApiException $e) {
      Log::error("Jira API Error: {$e->getMessage()}");
      return response()->json(['error' => 'Issue not found'], 404);
  }
  

• Webhooks: Use Jira’s webhooks to push events to Laravel (e.g., via GuzzleHttp\Client in a route):

  Route::post('/jira-webhook', function (Request $request) {
      $payload = $request->json()->all();
      // Process webhook (e.g., update Laravel DB)
  });
  

Gotchas and Tips

Pitfalls

1. Authentication:

   • API Tokens: Never use passwords directly. Generate API tokens for programmatic access.
   • OAuth: This library supports only Basic Auth. For OAuth, use GuzzleClient directly with custom middleware.

2. Endpoint Versioning:

   • The library defaults to /rest/api/2. For Cloud, use /rest/api/3 (update the base URL in GuzzleClient).
   • Cloud vs. Server: Some endpoints behave differently. Test in Jira’s REST Browser.

3. Pagination:

   • Endpoints like findAll() return paginated results. Use ->nextPage() or handle manually:

     $issues = [];
     $startAt = 0;
     do {
         $page = $issueEndpoint->findAll(['jql' => 'project = TEST', 'startAt' => $startAt]);
         $issues = array_merge($issues, $page);
         $startAt += count($page);
     } while (count($page) > 0);
     

4. Field Validation:

   • Jira rejects malformed issue data. Validate fields against Jira’s schema:

     $validFields = ['project', 'summary', 'description', 'issuetype'];
     $issueData = array_intersect_key($input, array_flip($validFields));
     

Debugging

1. Enable Guzzle Debugging: Add a GuzzleHandler to log requests:

   use GuzzleHttp\HandlerStack;
   use GuzzleHttp\Middleware;
   
   $client = new GuzzleClient(
       config('services.jira.url'),
       new BasicAuthentication(config('services.jira.email'), config('services.jira.token')),
       HandlerStack::create([
           Middleware::tap(function ($request) {
               Log::debug('Jira Request:', [
                   'url' => (string) $request->getUri(),
                   'method' => $request->getMethod(),
                   'body' => $request->getBody() ? $request->getBody()->getContents() : null,
               ]);
           }),
       ])
   );
   

2. Common HTTP Errors:

   • 403 Forbidden: Check API token permissions or IP restrictions in Jira.
   • 404 Not Found: Verify the endpoint URL (e.g., /rest/api/2/issue vs. /rest/api/3/issue).
   • 500 Server Error: Contact Jira admins or check Atlassian’s status page.

Extension Points

1. Custom Endpoints: Extend the library by creating new endpoints. Example:

   namespace App\Jira\Endpoint;
   
   use Bluetea\Api\Client\AbstractClient;
   use Bluetea\Api\Endpoint\AbstractEndpoint;
   
   class CustomEndpoint extends AbstractEndpoint {
       protected $basePath = 'custom';
   
       public function customAction($param) {
           return $this->client->get("{$this->basePath}/{$param}");
       }
   }
   

2. Middleware: Add request/response middleware to GuzzleClient:

   $client = new GuzzleClient(
       config('services.jira.url'),
       new BasicAuthentication(...),
       [],
       [
           'headers' => ['X-Atlassian-Token' => 'no-check'],
           'timeout' => 30,
       ]
   );
   

3. Testing: Mock the client in PHPUnit:

   $mockClient = $this->createMock(GuzzleClient::class);
   $mockClient->method('get')->willReturn(['issues' => []]);
   
   $issueEndpoint = new IssueEndpoint($mockClient);
   $result = $issueEndpoint->findAll([]);