Laravel GitHub Stats

https://github.com/jeffersongoncalves/laravel-github-stats
Admin
Laravel GitHub Stats is a self-hosted Laravel package that serves dynamic SVG cards displaying your...
Tokens:6,859
Snippets:70
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install with Composer

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Install the package via Composer.

```bash
composer require jeffersongoncalves/laravel-github-stats
```

--------------------------------

### GET /api/top-langs

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Retrieves a top languages card as an SVG image.

```APIDOC
## GET /api/top-langs

### Description
Returns a top languages card as an SVG image.

### Method
GET

### Endpoint
/api/top-langs

### Parameters
#### Query Parameters
- **theme** (string) - Optional - Theme for the card. Default: `tokyonight`. Options: `dark`, `radical`, `merko`, `gruvbox`, `onedark`, `tokyonight`.
- **hide_border** (boolean) - Optional - Hide the card border. Default: `false`. Options: `true`, `false`.
- **bg_color** (string) - Optional - Background color as hex without `#`. Default: per theme.
- **title_color** (string) - Optional - Title color as hex. Default: per theme.
- **text_color** (string) - Optional - Text color as hex. Default: per theme.
- **icon_color** (string) - Optional - Icon color as hex. Default: per theme.
- **border_color** (string) - Optional - Border color as hex. Default: per theme.

### Response
#### Success Response (200)
- **body** (SVG) - The top languages card as an SVG image.

#### Response Example
```svg
<svg ...>...</svg>
```
```

--------------------------------

### Get languages card data

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Fetches the top languages (default 8) aggregated from all repositories' language edges. Each language includes name, color, size, and percentage.

```php
$languages = $github->getLanguages();
// Returns top N languages (default 8) with: name, color, size, percentage
// Aggregated from all repositories' language edges
```

--------------------------------

### Embed GitHub stats cards in README

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Embed the GitHub stats cards in a README by placing these image tags in your markdown. The example uses the default tokyonight theme and hides borders for the stats and top-langs cards; the trophies card omits hide_border. Replace stats.yourdomain.com with your actual domain.

```markdown
<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>
```

--------------------------------

### GET /api/stats

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Retrieves a GitHub stats card as an SVG image.

```APIDOC
## GET /api/stats

### Description
Returns a GitHub stats card as an SVG image.

### Method
GET

### Endpoint
/api/stats

### Parameters
#### Query Parameters
- **theme** (string) - Optional - Theme for the card. Default: `tokyonight`. Options: `dark`, `radical`, `merko`, `gruvbox`, `onedark`, `tokyonight`.
- **hide_border** (boolean) - Optional - Hide the card border. Default: `false`. Options: `true`, `false`.
- **bg_color** (string) - Optional - Background color as hex without `#`. Default: per theme.
- **title_color** (string) - Optional - Title color as hex. Default: per theme.
- **text_color** (string) - Optional - Text color as hex. Default: per theme.
- **icon_color** (string) - Optional - Icon color as hex. Default: per theme.
- **border_color** (string) - Optional - Border color as hex. Default: per theme.

### Response
#### Success Response (200)
- **body** (SVG) - The GitHub stats card as an SVG image.

#### Response Example
```svg
<svg ...>...</svg>
```
```

--------------------------------

### GET /api/streak

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Retrieves a contribution streak card as an SVG image.

```APIDOC
## GET /api/streak

### Description
Returns a contribution streak card as an SVG image.

### Method
GET

### Endpoint
/api/streak

### Parameters
#### Query Parameters
- **theme** (string) - Optional - Theme for the card. Default: `tokyonight`. Options: `dark`, `radical`, `merko`, `gruvbox`, `onedark`, `tokyonight`.
- **hide_border** (boolean) - Optional - Hide the card border. Default: `false`. Options: `true`, `false`.
- **bg_color** (string) - Optional - Background color as hex without `#`. Default: per theme.
- **title_color** (string) - Optional - Title color as hex. Default: per theme.
- **text_color** (string) - Optional - Text color as hex. Default: per theme.
- **icon_color** (string) - Optional - Icon color as hex. Default: per theme.
- **border_color** (string) - Optional - Border color as hex. Default: per theme.

### Response
#### Success Response (200)
- **body** (SVG) - The contribution streak card as an SVG image.

#### Response Example
```svg
<svg ...>...</svg>
```
```

--------------------------------

### Get stats card data

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Retrieves the stats card data. The returned array includes name, total_stars, total_commits, total_prs, total_issues, total_reviews, followers, and total_repos.

```php
$stats = $github->getStats();
// Returns: name, total_stars, total_commits, total_prs, total_issues,
//          total_reviews, followers, total_repos
```

--------------------------------

### GET /api/trophies

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Retrieves an achievement trophies card as an SVG image.

```APIDOC
## GET /api/trophies

### Description
Returns an achievement trophies card as an SVG image.

### Method
GET

### Endpoint
/api/trophies

### Parameters
#### Query Parameters
- **theme** (string) - Optional - Theme for the card. Default: `tokyonight`. Options: `dark`, `radical`, `merko`, `gruvbox`, `onedark`, `tokyonight`.
- **hide_border** (boolean) - Optional - Hide the card border. Default: `false`. Options: `true`, `false`.
- **bg_color** (string) - Optional - Background color as hex without `#`. Default: per theme.
- **title_color** (string) - Optional - Title color as hex. Default: per theme.
- **text_color** (string) - Optional - Text color as hex. Default: per theme.
- **icon_color** (string) - Optional - Icon color as hex. Default: per theme.
- **border_color** (string) - Optional - Border color as hex. Default: per theme.
- **column** (integer) - Optional - Number of columns. Default: auto. Options: `1`–`10`.
- **no_frame** (boolean) - Optional - Disable frame. Default: `false`. Options: `true`, `false`.
- **no_bg** (boolean) - Optional - Disable background. Default: `false`. Options: `true`, `false`.

### Response
#### Success Response (200)
- **body** (SVG) - The achievement trophies card as an SVG image.

#### Response Example
```svg
<svg ...>...</svg>
```
```

--------------------------------

### GET /api/health

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Performs a health check on the service and returns a JSON response.

```APIDOC
## GET /api/health

### Description
Returns the service health check as a JSON response.

### Method
GET

### Endpoint
/api/health

### Response
#### Success Response (200)
- **body** (JSON) - The health check result.

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### Run composer analyse

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Run static analysis.

```bash
composer analyse
```

--------------------------------

### Run composer format

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Run code formatting.

```bash
composer format
```

--------------------------------

### Run composer test

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Run the test suite.

```bash
composer test
```

--------------------------------

### Publish Config File

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Publish the package configuration file.

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

--------------------------------

### Publish config file

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Run this Artisan command to publish the package configuration file. Use the tag github-stats-config.

```bash
php artisan vendor:publish --tag=github-stats-config
```

--------------------------------

### Config File: config/github-stats.php

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Configuration file for the package. Shows all options with defaults and environment variable bindings.

```php
// 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'    => [],
];
```

--------------------------------

### Development Commands (Pest, PHPStan, Pint, Artisan)

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Bash commands for running tests, static analysis, code formatting, and refreshing the GitHub stats cache.

```bash
# Run tests
vendor/bin/pest

# Run static analysis
vendor/bin/phpstan analyse

# Format code
vendor/bin/pint

# Refresh cache
php artisan github:refresh
```

--------------------------------

### Environment Variables for Configuration

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Environment variables for configuration. GITHUB_USERNAME and GITHUB_TOKEN are required; the rest are optional overrides with defaults shown.

```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
```

--------------------------------

### Service provider registration

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Registers services as singletons, sets up a rate limiter (60/min per IP) for 'github-stats', and aliases the LockUsername middleware. GitHubService depends on StreakCalculator.

```php
// Services are singletons
$this->app->singleton(ThemeService::class);
$this->app->singleton(StreakCalculator::class);
$this->app->singleton(GitHubService::class, function ($app) {
    return new GitHubService($app->make(StreakCalculator::class));
});

// Rate limiter: 60/min per IP
RateLimiter::for('github-stats', function (Request $request) {
    return Limit::perMinute(60)->by($request->ip());
});

// Middleware alias
$router->aliasMiddleware('github-stats.lock-username', LockUsername::class);
```

--------------------------------

### Namespace structure of GitHubStats

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Shows the directory and class layout of the package, including service provider, commands, controllers, middleware, and services.

```text
JeffersonGoncalves\GitHubStats\
    GitHubStatsServiceProvider          # Registers services, middleware, rate limiter
    Commands\
        RefreshGitHubStatsCommand       # php artisan github:refresh
    Http\
        Controllers\
            StatsController             # Renders SVG cards (stats, langs, streak, trophies, health)
        Middleware\
            LockUsername                # Blocks requests for other usernames
    Services\
        GitHubService                   # Fetches data from GitHub API, manages cache
        ThemeService                    # Resolves color themes with overrides
        StreakCalculator                # Computes current/longest streaks from contribution days
```

--------------------------------

### Cache refresh and cache keys

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Shows how to refresh all caches programmatically and via the artisan command. Lists the cache keys used: github:user_stats, github:languages, github:streak, github:trophies, github:svg:{card}:{hash}, and github:last_refresh.

```php
// Refresh all caches (clears data + SVG caches, re-warms data)
$github->refreshCache();

// Artisan command
php artisan github:refresh

// Cache keys:
// github:user_stats, github:languages, github:streak, github:trophies
// github:svg:{card}:{hash} (hash based on theme/color query params)
// github:last_refresh (ISO 8601 timestamp)
```

--------------------------------

### Environment variables for GitHub Stats

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Set these environment variables to configure the package. GITHUB_TOKEN requires a GitHub Personal Access Token with read:user scope (optionally repo). TTLs are in seconds.

```env
GITHUB_USERNAME=your-username
GITHUB_TOKEN=ghp_your_personal_access_token
GITHUB_STATS_DATA_TTL=14400
GITHUB_STATS_SVG_TTL=3600
GITHUB_STATS_THEME=tokyonight
GITHUB_STATS_ROUTE_PREFIX=api
```

--------------------------------

### Docker Compose deployment configuration

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Docker Compose configuration for deploying the app with Redis as a dependency.

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

--------------------------------

### GitHubService data fetching calls

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Shows the three data-fetching calls used by GitHubService: GraphQL with pagination for user data, REST for all-time commit count, and year-by-year contributions.

```php
// Fetches: name, login, avatarUrl, followers, following, repositories (paginated),
// contributionsCollection (commits, issues, PRs, reviews, calendar)
$userData = $this->fetchUserData();

// REST API for all-time commit count
$allTimeCommits = $this->fetchAllTimeCommits();

// Year-by-year contributions from account creation to now
$allTime = $this->fetchAllTimeContributions();
```

--------------------------------

### Run github:refresh command

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Run the scheduled command to refresh the GitHub stats cache manually.

```bash
php artisan github:refresh
```

--------------------------------

### GitHub Stats Configuration (config/github-stats.php)

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Configuration file for the Laravel GitHub Stats package. Sets GitHub username, token, cache TTLs, API URLs, default theme and display options, route prefix, and middleware. Environment variables can override defaults.

```php
// config/github-stats.php
return [
    'username' => env('GITHUB_USERNAME', 'jeffersongoncalves'),
    'token' => env('GITHUB_TOKEN'),
    'cache' => [
        'data_ttl' => (int) env('GITHUB_STATS_DATA_TTL', 14400), // 4 hours
        'svg_ttl' => (int) env('GITHUB_STATS_SVG_TTL', 3600),    // 1 hour
    ],
    'graphql_url' => 'https://api.github.com/graphql',
    'rest_url' => 'https://api.github.com',
    'defaults' => [
        'theme' => env('GITHUB_STATS_THEME', 'tokyonight'),
        'hide_border' => false,
        'show_icons' => true,
        'langs_count' => 8,
    ],
    'route_prefix' => env('GITHUB_STATS_ROUTE_PREFIX', 'api'),
    'middleware' => [],
];
```

--------------------------------

### Theme resolution and available themes

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Resolves a theme with optional color overrides (hex values without #) and lists available themes: tokyonight, dark, radical, merko, gruvbox, onedark. Each theme has five color slots: bg, title, text, icon, border.

```php
$theme = app(ThemeService::class)->resolve('tokyonight', [
    'bg_color' => '0d1117',     // Override specific colors
    'title_color' => 'ff0000',  // Hex values without #
]);

// Available themes: tokyonight, dark, radical, merko, gruvbox, onedark
$themes = app(ThemeService::class)->availableThemes();
```

--------------------------------

### Testing Theme Resolution with Overrides

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Pest test for ThemeService::resolve, verifying that custom overrides (bg_color) are applied and default dark theme title is used when not overridden.

```php
it('resolves theme with overrides', function () {
    $theme = app(ThemeService::class)->resolve('dark', [
        'bg_color' => 'ffffff',
    ]);

    expect($theme['bg'])->toBe('ffffff');
    expect($theme['title'])->toBe('58a6ff'); // Default dark theme title
});
```

--------------------------------

### Schedule github:refresh every four hours

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/README.md

Add the github:refresh command to the Laravel scheduler to run every four hours.

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

--------------------------------

### Mocking GitHub API Responses with Http::fake

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Pest test that fakes GitHub GraphQL and REST API responses to test the GitHubService. Uses Http::fake to return predefined data for the GraphQL endpoint and search commits endpoint, then asserts the service returns expected keys.

```php
use Illuminate\Support\Facades\Http;

it('fetches user stats', function () {
    Http::fake([
        'api.github.com/graphql' => Http::response([
            'data' => ['user' => [
                'name' => 'Test User',
                'login' => 'testuser',
                'avatarUrl' => 'https://example.com/avatar.png',
                'createdAt' => '2020-01-01T00:00:00Z',
                'followers' => ['totalCount' => 100],
                'following' => ['totalCount' => 50],
                'repositories' => [
                    'totalCount' => 30,
                    'nodes' => [],
                    'pageInfo' => ['hasNextPage' => false, 'endCursor' => null],
                ],
                'contributionsCollection' => [
                    'totalCommitContributions' => 500,
                    'totalIssueContributions' => 20,
                    'totalPullRequestContributions' => 50,
                    'totalPullRequestReviewContributions' => 10,
                    'restrictedContributionsCount' => 0,
                    'contributionCalendar' => ['totalContributions' => 580, 'weeks' => []],
                ],
            ]],
        ]),
        'api.github.com/search/commits*' => Http::response(['total_count' => 1200]),
    ]);

    $stats = app(GitHubService::class)->getStats();

    expect($stats)->toHaveKeys(['total_stars', 'total_commits', 'total_prs']);
});
```

--------------------------------

### Calculate streak data

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Calculates streak data from contribution calendar days. Returns current_streak, longest_streak, total_contributions, and start/end dates for both streaks. Current streak allows today to have zero contributions (checks yesterday).

```php
$result = $streakCalculator->calculate($days);
// Returns: current_streak, longest_streak, total_contributions,
//          current_streak_start, current_streak_end,
//          longest_streak_start, longest_streak_end
```

--------------------------------

### Route group for SVG card endpoints

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Defines the SVG card endpoints under a configurable prefix with throttle and lock-username middleware. Routes include /stats, /top-langs, /streak, /trophies, and /health.

```php
// routes/api.php
Route::group([
    'prefix' => config('github-stats.route_prefix', 'api'),
    'middleware' => ['throttle:github-stats', 'github-stats.lock-username', ...],
], function () {
    Route::get('/stats', [StatsController::class, 'stats']);
    Route::get('/top-langs', [StatsController::class, 'topLangs']);
    Route::get('/streak', [StatsController::class, 'streak']);
    Route::get('/trophies', [StatsController::class, 'trophies']);
    Route::get('/health', [StatsController::class, 'health']);
});
```

--------------------------------

### Testing Streak Calculator

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Pest test for StreakCalculator::calculate, using a three-day array of contribution counts to verify current and longest streak calculations.

```php
it('calculates current streak', function () {
    $days = [
        ['date' => now()->subDays(2)->format('Y-m-d'), 'contributionCount' => 3],
        ['date' => now()->subDay()->format('Y-m-d'), 'contributionCount' => 5],
        ['date' => now()->format('Y-m-d'), 'contributionCount' => 1],
    ];

    $result = app(StreakCalculator::class)->calculate($days);

    expect($result['current_streak'])->toBe(3);
    expect($result['longest_streak'])->toBe(3);
});
```

--------------------------------

### SVG response headers

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Lists the response headers included in all SVG responses: Content-Type, Cache-Control, ETag (based on md5 of SVG), and Expires (one hour from now).

```php
// All SVG responses include:
'Content-Type' => 'image/svg+xml; charset=utf-8',
'Cache-Control' => 'public, max-age=3600, s-maxage=3600',
'ETag' => '"' . md5($svg) . '"',
'Expires' => now()->addHour()->toRfc7231String(),
```

--------------------------------

### Trophy thresholds

Source: https://github.com/jeffersongoncalves/laravel-github-stats/blob/main/resources/boost/skills/github-stats-development/SKILL.md

Lists the trophy categories and their S-tier thresholds. Trophies are awarded based on these thresholds with levels S, A, B, C, D, or none.

```php
// Trophy categories and S-tier thresholds:
// Stars: 1000, Commits: 5000, Pull Requests: 500, Issues: 500,
// Repos: 100, Followers: 1000, Reviews: 500
```
Tokens:
Raw