Github Bundle Laravel Package

Getting Started

Minimal Steps to First Use

1. Installation Run in your Symfony project root:

   composer require common-gateway/github-bundle:dev-main
   

   For Dockerized environments:

   docker-compose exec php composer require common-gateway/github-bundle:dev-main
   

2. Install Entities & Schemas Execute the bundle’s installation command:

   php bin/console commongateway:install common-gateway/github-bundle
   

   This generates Doctrine entities and database migrations for GitHub issue CRUD operations.

3. First Use Case: Fetching Issues Inject the CommonGateway\GithubBundle\Service\GithubService into a controller or command:

   use CommonGateway\GithubBundle\Service\GithubService;
   
   class IssueController extends AbstractController
   {
       public function __construct(private GithubService $githubService) {}
   
       public function listIssues(): Response
       {
           $issues = $this->githubService->getIssues('owner', 'repo');
           return $this->render('issues/index.html.twig', ['issues' => $issues]);
       }
   }
   

4. Configuration Add GitHub credentials to .env:

   GITHUB_TOKEN=your_github_personal_access_token
   GITHUB_API_URL=https://api.github.com
   

Implementation Patterns

Core Workflows

1. CRUD Operations The bundle abstracts GitHub API interactions for issues:

   • List Issues:

     $this->githubService->getIssues('symfony', 'symfony');
     

   • Create Issue:

     $this->githubService->createIssue('symfony', 'symfony', [
         'title' => 'Bug Report',
         'body'  => 'Description...',
     ]);
     

   • Update/Delete: Use updateIssue() and deleteIssue() with issue IDs.

2. Event-Driven Integrations Extend the bundle’s event system to trigger actions on issue events (e.g., IssueOpenedEvent):

   // config/services.yaml
   CommonGateway\GithubBundle\EventListener\IssueListener:
       tags:
           - { name: kernel.event_listener, event: issue.opened, method: onIssueOpened }
   

3. Doctrine Integration The bundle generates entities for issues (e.g., Issue, Comment). Use them in repositories:

   $repository = $this->getDoctrine()->getRepository(Issue::class);
   $openIssues = $repository->findBy(['state' => 'open']);
   

4. API Rate Limiting Handle GitHub API rate limits via middleware or the bundle’s built-in retry logic:

   $this->githubService->setRetryLimit(3); // Retry failed requests 3 times
   

Integration Tips

• Symfony Forms: Bind GitHub issue data to forms for user-friendly CRUD:

  $form = $this->createFormBuilder($issue)
      ->add('title', TextType::class)
      ->add('body', TextareaType::class)
      ->getForm();
  

• Twig Templates: Use the issues Twig extension to render issue lists:

  {% for issue in issues %}
      <h3>{{ issue.title }}</h3>
      <p>{{ issue.body|truncate(100) }}</p>
  {% endfor %}
  

• Console Commands: Schedule issue syncs with Symfony’s command bus:

  php bin/console app:sync-github-issues owner repo
  

Gotchas and Tips

Pitfalls

1. Authentication

   • Gotcha: The bundle expects a GitHub Personal Access Token (PAT) with repo scope. Without it, API calls fail silently.
   • Fix: Verify .env and test with:

     $this->githubService->getRateLimit(); // Throws exception if token is invalid
     

2. Rate Limits

   • Gotcha: GitHub’s API enforces rate limits. The bundle does not auto-paginate or cache responses.
   • Fix: Implement caching (e.g., Symfony Cache component) or use the GithubService::setCache() method if available.

3. Entity Mismatches

   • Gotcha: The generated Issue entity may not map 1:1 to GitHub’s API. Fields like labels or assignees might require custom serialization.
   • Fix: Extend the entity or override the bundle’s hydrator:

     // src/Entity/Issue.php
     use CommonGateway\GithubBundle\Entity\BaseIssue;
     
     class Issue extends BaseIssue {
         public function __construct() {
             $this->labels = new ArrayCollection();
         }
     }
     

4. Database Schema

   • Gotcha: Running commongateway:install overwrites existing entities if they conflict. Backup your database first.
   • Fix: Use --dry-run flag to preview changes:

     php bin/console doctrine:schema:update --dry-run
     

Debugging

1. Enable API Debugging Add this to config/packages/dev/github_bundle.yaml:

   github_bundle:
       debug: true
   

   Logs API requests/responses to var/log/dev.log.

2. Common Errors

   • 404 Not Found: Verify repository name/case sensitivity (GitHub is case-sensitive).
   • 403 Forbidden: Ensure the token has repo scope and the user has access to the repo.
   • 500 Server Error: Check GitHub’s status page for outages.

Extension Points

1. Custom API Endpoints Extend GithubService to support non-issue endpoints (e.g., pull requests):

   // src/Service/ExtendedGithubService.php
   class ExtendedGithubService extends GithubService {
       public function getPullRequests(string $owner, string $repo): array {
           return $this->client->getCollection('repo/pulls', [
               'owner' => $owner,
               'repo'  => $repo,
           ]);
       }
   }
   

2. Webhook Listeners Add a listener for GitHub webhooks (requires symfony/http-client):

   // src/EventListener/GithubWebhookListener.php
   class GithubWebhookListener {
       public function onWebhook(Request $request, GithubService $githubService) {
           $payload = json_decode($request->getContent(), true);
           if ($payload['action'] === 'opened') {
               $githubService->createComment($payload['issue']['number'], 'Auto-comment!');
           }
       }
   }
   

3. Testing Mock GithubService in tests:

   $mockService = $this->createMock(GithubService::class);
   $mockService->method('getIssues')->willReturn([$mockIssue]);
   $this->container->set(GithubService::class, $mockService);