#Laravel GitHub Contributions

Fetch the GitHub contribution calendar for any login as a flat 0-4 heatmap-cell array — ready to render your own contribution heatmap. The cells are ordered the same way GitHub renders the calendar: column-major (week-by-week, top→bottom), seven cells per week.

This package returns raw heatmap-cell data. If you instead want ready-made profile SVG cards (stats, top languages, streaks, trophies), use jeffersongoncalves/laravel-github-stats.

#Installation

composer require jeffersongoncalves/laravel-github-contributions

Publish the config file (optional):

php artisan vendor:publish --tag="laravel-github-contributions-config"

#Configuration

Add to your .env:

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Create a Personal Access Token with the read:user scope.

#Config Options

// config/github-contributions.php
return [
    // Falls back to config('services.github.token') when empty.
    'token' => env('GITHUB_TOKEN'),

    'user_agent' => env('GITHUB_CONTRIBUTIONS_USER_AGENT', 'laravel-github-contributions'),

    'timeout' => (int) env('GITHUB_CONTRIBUTIONS_TIMEOUT', 8),

    // Cache responses (keyed by login) to stay under the 5000/hr API limit.
    // Set ttl to 0 to disable caching entirely.
    'cache' => [
        'ttl' => (int) env('GITHUB_CONTRIBUTIONS_CACHE_TTL', 3600),
    ],
];

#Usage

use JeffersonGoncalves\GitHubContributions\GitHubContributions;

$data = GitHubContributions::fetch('jeffersongoncalves');

// [
//     'cells' => [0, 1, 0, 2, 4, 3, 0, ...], // list<int 0-4>, 7 per week, column-major
//     'total' => 1234,                        // total contributions in the calendar window
// ]

Each value in cells is a contribution level mapped from GitHub's contributionLevel enum:

When no token is configured (neither github-contributions.token nor services.github.token) or the GitHub API request fails, fetch() returns ['cells' => [], 'total' => 0].

#Testing

composer test

#Static Analysis

composer analyse

#Code Formatting

composer format

#Changelog

Please see CHANGELOG for more information on what has changed recently.

#License

The MIT License (MIT). Please see License File for more information.