Github Contributions Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require digitalkaoz/github-contributions-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Digitalkaoz\GithubContributionsBundle\DigitalkaozGithubContributionsBundle::class => ['all' => true],
   ];
   

2. Configuration Add GitHub credentials to config/packages/digitalkaoz_github_contributions.yaml:

   digitalkaoz_github_contributions:
       github_username: 'your_github_username'
       github_token: '%env(GITHUB_TOKEN)%'  # Store token in .env
   

3. First Use Case Render the contribution calendar in a Twig template:

   {{ render(controller('DigitalkaozGithubContributionsBundle:Default:contributions')) }}
   

   Or fetch data programmatically:

   $contributions = $this->get('digitalkaoz_github_contributions.service')->getContributions();
   

Implementation Patterns

Common Workflows

1. Dynamic User Profiles

   • Use dependency injection to fetch contributions for multiple users:

     $service = $this->container->get('digitalkaoz_github_contributions.service');
     $contributions = $service->getContributions('octocat'); // Dynamic username
     

2. Caching Contributions

   • Leverage Symfony’s cache system to avoid API rate limits:

     # config/packages/digitalkaoz_github_contributions.yaml
     digitalkaoz_github_contributions:
         cache_enabled: true
         cache_lifetime: 3600  # 1 hour
     

3. Twig Integration

   • Pass contributions to templates for custom rendering:

     return $this->render('profile/show.html.twig', [
         'contributions' => $contributions,
         'username' => 'your_github_username'
     ]);
     

   • Use Twig extensions for helper methods:

     {% if contribution.isActive() %}
         <div class="active-day">...</div>
     {% endif %}
     

4. API-Driven Apps

   • Expose contributions via an API endpoint:

     use Symfony\Component\HttpFoundation\JsonResponse;
     
     public function getContributionsApi(Request $request)
     {
         $username = $request->query->get('username');
         $data = $this->get('digitalkaoz_github_contributions.service')->getContributions($username);
         return new JsonResponse($data);
     }
     

Gotchas and Tips

Pitfalls

1. Rate Limiting

   • GitHub’s API enforces rate limits. Cache responses aggressively or implement retry logic with exponential backoff.

2. Token Permissions

   • Ensure your GitHub token has public_repo scope if fetching contributions for private repos (though contributions are public by default).

3. Deprecated Methods

   • The bundle uses GitHub’s legacy API (/users/:username/contributions). Migrate to the GraphQL API for future-proofing:

     // Example GraphQL query (requires custom implementation)
     $query = '
         query {
           user(login: "your_username") {
             contributionsCollection {
               contributionCalendar {
                 totalContributions
                 weeks {
                   contributionDays {
                     contributionCount
                     date
                   }
                 }
               }
             }
           }
         }
     ';
     

4. Twig Template Overrides

   • Override the default Twig template (templates/Default/contributions.html.twig) by placing a custom version in templates/DigitalkaozGithubContributionsBundle/Default/contributions.html.twig.

Debugging

• Enable Debug Mode Set debug: true in the config to log API responses:

  digitalkaoz_github_contributions:
      debug: true
  

• Validate Token Test your token at GitHub Token Testing to ensure it has the correct permissions.

Extension Points

1. Custom Data Transformers

   • Extend the Contribution class to add metadata (e.g., PR counts, issue comments):

     namespace App\Entity;
     
     use Digitalkaoz\GithubContributionsBundle\Entity\Contribution as BaseContribution;
     
     class Contribution extends BaseContribution
     {
         public function getPrCount(): int
         {
             // Custom logic to fetch PR data
         }
     }
     

2. Event Listeners

   • Hook into the contributions.fetch event to modify data before rendering:

     // src/EventListener/ContributionListener.php
     public function onContributionsFetch(GetContributionsEvent $event)
     {
         $contributions = $event->getContributions();
         // Modify $contributions array
         $event->setContributions($contributions);
     }
     

     Register the listener in services.yaml:

     services:
         App\EventListener\ContributionListener:
             tags:
                 - { name: 'kernel.event_listener', event: 'contributions.fetch' }
     

3. Alternative Data Sources

   • Replace the GitHub service with a mock or alternative provider (e.g., GitLab) by implementing Digitalkaoz\GithubContributionsBundle\Service\ContributionServiceInterface.