README

Laravel GitHub Stats

Self-hosted Laravel package that serves dynamic SVG cards with your GitHub statistics. Replace unreliable third-party services (github-readme-stats, streak-stats, github-profile-trophy) with your own private service.

Features

• Stats Card — Total Stars, Commits, PRs, Issues, Followers
• Top Languages Card — Horizontal bar chart with top 8 languages
• Streak Card — Current Streak, Longest Streak, Total Contributions
• Trophies Card — Achievement badges with rank levels (S/A/B/C/D)
• 6 Built-in Themes — tokyonight, dark, radical, merko, gruvbox, onedark
• Custom Colors — Override any color via query parameters
• Aggressive Caching — Two-layer cache (4h data + 1h SVG)
• Username Locked — Service locked to a single username via .env
• Background Refresh — Scheduled command to keep cache warm

Installation

composer require jeffersongoncalves/laravel-github-stats

Publish the config file:

php artisan vendor:publish --tag="github-stats-config"

Configuration

Add to your .env:

GITHUB_USERNAME=jeffersongoncalves
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Create a Personal Access Token with read:user scope. Add repo scope if you want private repository stats.

Config Options

// config/github-stats.php
return [
    'username' => env('GITHUB_USERNAME', 'jeffersongoncalves'),
    'token'    => env('GITHUB_TOKEN'),

    'cache' => [
        'data_ttl' => 14400, // 4 hours
        'svg_ttl'  => 3600,  // 1 hour
    ],

    'defaults' => [
        'theme'       => 'tokyonight',
        'hide_border' => false,
        'show_icons'  => true,
        'langs_count' => 8,
    ],

    'route_prefix' => 'api',
    'middleware'    => [],
];

Endpoints

Query Parameters

Usage in GitHub README

<div align="center">
  <img height="180em"
    src="https://stats.yourdomain.com/api/stats?theme=tokyonight&hide_border=true" />
  <img height="180em"
    src="https://stats.yourdomain.com/api/top-langs?theme=tokyonight&hide_border=true" />
</div>

<div align="center">
  <img src="https://stats.yourdomain.com/api/streak?theme=tokyonight&hide_border=true" />
</div>

<div align="center">
  <img src="https://stats.yourdomain.com/api/trophies?theme=tokyonight" />
</div>

Cache Refresh

The package includes a scheduled command to keep the cache warm:

php artisan github:refresh

Add to your scheduler (in routes/console.php or app/Console/Kernel.php):

Schedule::command('github:refresh')->everyFourHours();

Deployment

Option A — VPS with Forge/Ploi

1. Provision a small VPS (1 vCPU, 1GB RAM)
2. Deploy your Laravel app with this package
3. Set .env variables
4. Setup Redis for caching
5. Configure scheduler: * * * * * php artisan schedule:run
6. Point subdomain: stats.yourdomain.com
7. SSL via Let's Encrypt

Option B — Docker

services:
  app:
    build: .
    ports: ["8080:80"]
    environment:
      GITHUB_USERNAME: jeffersongoncalves
      GITHUB_TOKEN: ${GITHUB_TOKEN}
    depends_on: [redis]
  redis:
    image: redis:alpine

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.