#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

# Optional overrides (defaults shown)
GITHUB_STATS_DATA_TTL=14400
GITHUB_STATS_SVG_TTL=3600
GITHUB_STATS_THEME=tokyonight
GITHUB_STATS_ROUTE_PREFIX=api

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.