Issues Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require digitalkaoz/issues@dev-main
   

   (Note: Due to the package's age, ensure your composer.json allows PHP 7.4+ for full compatibility with the latest changes.)

2. Basic Initialization

   use Digitalkaoz\Issues\IssueTracker;
   
   $tracker = new IssueTracker('bitbucket', [
       'username' => 'your_username',
       'token'    => 'your_app_password_or_token',
   ]);
   

3. First Use Case: Fetching Issues

   $issues = $tracker->issues()->all();
   // Returns an array of issue objects (e.g., for Bitbucket: title, id, labels, etc.)
   

4. Where to Look First

   • Documentation: Check the GitHub repo for updated examples in the examples/ folder.
   • Config: Review config/issues.php (auto-generated) or the constructor parameters for Bitbucket-specific options like workspace.
   • Examples: Look for tests/ or examples/ folders for Bitbucket-specific usage snippets.

Implementation Patterns

Common Workflows

1. Tracker-Specific Operations

   // Bitbucket example
   $tracker = new IssueTracker('bitbucket', [
       'token'     => 'your_app_password',
       'workspace' => 'your_workspace',
   ]);
   $repoIssues = $tracker->issues()->repo('your-repo')->open()->fetch();
   

2. Querying Issues

   // Filter by label and state (Bitbucket-specific fields)
   $issues = $tracker->issues()
       ->labels(['bug', 'critical'])
       ->state('open')
       ->fetch();
   

3. Creating/Updating Issues

   $newIssue = $tracker->issues()->create([
       'title'  => 'Fix login bug',
       'content' => 'Users cannot log in after update.', // Note: Bitbucket uses 'content' instead of 'body'
       'labels' => ['bug', 'auth'],
   ]);
   

4. Integration with Laravel

   • Service Provider:

     $this->app->singleton(IssueTracker::class, function ($app) {
         return new IssueTracker(
             config('issues.tracker'),
             config('issues.credentials') + ['workspace' => config('issues.bitbucket.workspace')]
         );
     });
     

   • Facade (Optional): Create a facade (IssuesFacade) to simplify calls:

     Issues::tracker('bitbucket')->issues()->all();
     

5. Batch Processing

   foreach ($tracker->issues()->all() as $issue) {
       if ($issue->isOlderThan('30 days')) {
           $tracker->issues()->update($issue->id, ['labels' => ['stale']]);
       }
   }
   

Integration Tips

• API Rate Limits: Implement retry logic for rate-limited trackers (e.g., Bitbucket).
• Caching: Cache responses for all() or fetch() calls using Laravel’s cache:

  $issues = Cache::remember("issues_{$repo}", now()->addHours(1), function () use ($tracker) {
      return $tracker->issues()->repo($repo)->all();
  });
  

• Events: Dispatch Laravel events (e.g., IssueCreated, IssueUpdated) after tracker operations.
• Notifications: Use Laravel Notifications to alert users about new issues:

  event(new IssueCreated($newIssue));
  

Gotchas and Tips

Pitfalls

1. Bitbucket-Specific Fields

   • Bitbucket uses content instead of body for issue descriptions.
   • Workaround: Normalize data in a Laravel model:

     class Issue {
         public function __construct(array $data) {
             $this->title = $data['title'] ?? '';
             $this->description = $data['content'] ?? $data['body'] ?? '';
             $this->labels = collect($data['labels'] ?? []);
         }
     }
     

2. Authentication Issues

   • Bitbucket: Use an App Password or OAuth token.
   • Debugging: Check the raw API response with:

     $tracker->getClient()->setDebug(true); // If the package uses Guzzle.
     

3. Workspace Requirement

   • Bitbucket requires a workspace parameter in the credentials. Add it to your config:

     'bitbucket' => [
         'workspace' => env('BITBUCKET_WORKSPACE'),
     ],
     

4. Deprecated Trackers

   • Some older trackers (e.g., Trello) may still be present but unsupported. Avoid using them.
   • Workaround: Extend the base IssueTracker class for custom APIs.

Debugging Tips

• Enable Verbose Output:

  $tracker->setLogLevel(IssueTracker::LOG_DEBUG);
  

• Inspect Raw API Calls: Use a tool like Postman to compare requests/responses with the package’s behavior.
• Check HTTP Status Codes: Wrap calls in a try-catch to log errors:

  try {
      $issues = $tracker->issues()->all();
  } catch (\Exception $e) {
      Log::error("Tracker error: " . $e->getMessage(), ['response' => $e->getResponse()]);
  }
  

Extension Points

1. Custom Trackers Extend Digitalkaoz\Issues\IssueTracker and override:

   • getApiUrl(): Change the base API endpoint.
   • authenticate(): Implement custom auth logic for Bitbucket or other trackers.
   • parseIssue(): Modify how issue data is structured for Bitbucket-specific fields.

2. Laravel Service Container Bind the tracker to the container with custom configurations:

   $this->app->bind(IssueTracker::class, function ($app) {
       return new IssueTracker(
           config('issues.tracker'),
           $app['config']['issues.credentials'] + ['debug' => env('ISSUES_DEBUG', false)]
       );
   });
   

3. Testing Mock the tracker in tests:

   $mockTracker = Mockery::mock(IssueTracker::class)->makePartial();
   $mockTracker->shouldReceive('issues')->andReturnSelf();
   $mockTracker->shouldReceive('all')->andReturn([/* mock issues */]);
   

4. Webhooks For real-time updates, pair with a webhook listener (e.g., Laravel’s HandleIncomingWebhook):

   // In a webhook route:
   $payload = json_decode(request()->getContent(), true);
   Issues::tracker('bitbucket')->issues()->syncFromWebhook($payload);