Issues Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require digitalkaoz/issues-bundle
   

   Add the bundle to app/AppKernel.php:

   new Rs\IssuesBundle\RsIssuesBundle(),
   

2. Basic Configuration (config.yml):

   rs_issues:
       github:
           - "digitalkaoz/issues"  # Track a single repo
   

3. First Use Case: Inject the Rs\IssuesBundle\Service\IssuesService into a controller/service:

   use Rs\IssuesBundle\Service\IssuesService;
   
   class IssueController extends Controller
   {
       public function __construct(private IssuesService $issuesService) {}
   
       public function showIssues()
       {
           $issues = $this->issuesService->getIssues('github', 'digitalkaoz/issues');
           return $this->renderIssues($issues);
       }
   }
   

Implementation Patterns

Core Workflows

1. Issue Tracking Integration:

   • Use the service to fetch issues from configured trackers (GitHub, Jira, GitLab) in a unified way:

     $githubIssues = $issuesService->getIssues('github', 'vendor/repo');
     $jiraIssues   = $issuesService->getIssues('jira', 'PROJKEY');
     

2. Dynamic Repo Matching:

   • Leverage regex patterns to track multiple repos (e.g., symfony/* or doctrine/(?!common).*).
   • Example: Track all repos under an org except specific ones:

     rs_issues:
         github:
             - "symfony/*"
             - "!symfony/symfony"  # Exclude a repo
     

3. Authentication Handling:

   • For private repos, configure credentials in parameters.yml (e.g., GITHUB_TOKEN or JIRA_PASSWORD).
   • Reference them in config:

     rs_issues:
         jira:
             - "https://jira.com PROJKEY %env(JIRA_USER)% %env(JIRA_PASSWORD)%"
     

4. Event-Driven Updates:

   • Extend the bundle to trigger issue checks on Git events (e.g., post-commit or post-push):

     // In a Git hook or command
     $issuesService->checkForNewIssues('github', 'digitalkaoz/issues');
     

5. Caching:

   • Cache issue responses to reduce API calls (e.g., using Symfony’s Cache component):

     $cache = $this->container->get('cache.app');
     $issues = $cache->get('issues:github:digitalkaoz/issues', function() use ($issuesService) {
         return $issuesService->getIssues('github', 'digitalkaoz/issues');
     });
     

Gotchas and Tips

Pitfalls

1. Regex Complexity:

   • Overly complex repo patterns (e.g., nested negations) may fail silently. Test patterns with tools like regex101.com first.
   • Example of a fragile pattern:

     - "doctrine/(?!common|lexer)(?!orm)(.*)"  # May exclude unintended repos
     

2. Authentication Failures:

   • Hardcoded credentials in config.yml are insecure. Always use parameters.yml or environment variables:

     # ❌ Avoid
     rs_issues:
         github:
             - "vendor/repo %plaintext_token%"
     
     # ✅ Use
     rs_issues:
         github:
             - "vendor/repo %env(GITHUB_TOKEN)%"
     

3. API Rate Limits:

   • GitHub/GitLab/Jira APIs throttle requests. Implement exponential backoff or caching:

     try {
         $issues = $issuesService->getIssues('github', 'repo');
     } catch (RateLimitExceededException $e) {
         sleep(60); // Wait and retry
         retry();
     }
     

4. Bundle Maturity:

   • The package has 0 stars and 0 dependents, suggesting limited testing. Validate behavior with edge cases (e.g., empty repos, malformed responses).

5. Symfony Version Compatibility:

   • The bundle may not support newer Symfony versions (e.g., 6.x). Check composer.json for symfony/* constraints.

Debugging Tips

1. Enable Verbose Logging: Add to config.yml:

   rs_issues:
       debug: true
   

   Logs will appear in var/log/dev.log.

2. Inspect Raw API Responses: Override the service to dump responses:

   $issuesService->setDebugHandler(function($tracker, $response) {
       file_put_contents('debug/issues.json', json_encode($response));
   });
   

3. Test with Public Repos: Start with public repos (e.g., symfony/symfony) to avoid auth issues:

   rs_issues:
       github:
           - "symfony/symfony"
   

Extension Points

1. Custom Trackers: Extend the Rs\IssuesBundle\Tracker\TrackerInterface to support new issue trackers (e.g., GitHub Enterprise, Azure DevOps):

   class CustomTracker implements TrackerInterface {
       public function fetchIssues(string $repo): array {
           // Implement custom logic
       }
   }
   

   Register it in the bundle’s services.

2. Issue Filtering: Add a filter layer to the service to transform raw issues (e.g., normalize labels or statuses):

   $issuesService->addFilter(function(array $issues) {
       return array_map(function($issue) {
           $issue['status'] = strtolower($issue['status']);
           return $issue;
       }, $issues);
   });
   

3. Webhook Integration: Create a command to process webhook payloads and update issues:

   // src/Command/ProcessWebhookCommand.php
   class ProcessWebhookCommand extends Command {
       protected function execute(InputInterface $input, OutputInterface $output) {
           $payload = json_decode(file_get_contents('php://input'), true);
           $this->issuesService->handleWebhook($payload);
       }
   }