jeffersongoncalves/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.

v1.0.0 2026-06-20 19:51 UTC

Requires

• php: ^8.2
• illuminate/support: ^11.0|^12.0|^13.0
• spatie/laravel-package-tools: ^1.14.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.21
• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.0|^4.0
• pestphp/pest-plugin-laravel: ^3.0|^4.0

MIT

• Jefferson Gonçalves

• github
• calendar
• laravel
• profile
• heatmap
• graphql
• contributions
• contribution-graph

README

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),
];

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:

GitHub level	Cell
NONE	0
FIRST_QUARTILE	1
SECOND_QUARTILE	2
THIRD_QUARTILE	3
FOURTH_QUARTILE	4

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.