/github-gists-blog

Transform GitHub Gists into a beautiful blog interface with caching support

Primary LanguagePHP

GitHub Gist Blog

Transform GitHub Gists into blog interfaces with caching and real-time updates.

🚀 Features

  • Dynamic Blog Generation: Convert any GitHub user's public gists into a blog-style interface
  • Smart Caching: 4-hour cache with background refresh for optimal performance
  • Real-time Search: Livewire-powered filtering by username and programming language
  • Queue-based Updates: Background job processing for seamless user experience
  • Responsive Design: Beautiful Tailwind CSS interface that works on all devices

🛠 Tech Stack

  • Backend: Laravel 12, PHP 8.4+
  • Frontend: Blade templates, Livewire, Alpine.js, Tailwind CSS
  • Database: PostgreSQL
  • Cache: Redis
  • Queue: Laravel queues with Redis driver
  • API: GitHub REST API v3
  • Local Development: Laravel Sail

📋 Prerequisites

  • PHP 8.4 or higher
  • Docker (for local Development)
  • Composer
  • Node.js & NPM
  • PostgreSQL
  • Redis (for production)
  • GitHub Personal Access Token

🔧 Local Development Setup

1. Clone and Install Dependencies

git clone https://github.com/Braunson/github-gists-blog.git
cd github-gists-blog
composer install
npm install

2. Environment Configuration

cp .env.example .env
php artisan key:generate

Update your .env file:

# GitHub API Token (public access only needed)
GITHUB_TOKEN=your_github_personal_access_token

3. Database Setup

php artisan migrate

4. Build Assets & Start Development

# Build frontend assets
npm run build

# Start Laravel development server
php artisan serve

# In another terminal, start queue worker
php artisan queue:work

Visit http://localhost to see the application.

🚀 Laravel Cloud Deployment

1. Prepare Repository

  • Ensure your code is committed and pushed

2. Laravel Cloud Setup

  1. Connect Repository:

    • Log into Laravel Cloud
    • Create new project
    • Connect your GitHub repository

  2. Environment Variables: Configure these in Laravel Cloud environment:

    GITHUB_TOKEN=your_github_token

  3. Database Configuration:

    • Laravel Cloud provides PostgreSQL automatically
    • Database credentials are auto-configured

  4. Redis Configuration:

    • Laravel Cloud provides Redis automatically
    • Cache and session drivers are auto-configured

  5. Queue Configuration:

    • Laravel Cloud sets your queue connection as automatically (assuming you configured them ahead of time)
    • Laravel Cloud will auto-start queue workers

3. Deploy

  • Set up push to deploy in Laravel Cloud or manually deploy in the Laravel Cloud UI.

4. Post-Deployment

# Run migrations on production with seeds (optional)
# NOTE: Laravel Cloud will automatically run this by default on a deploy excluding the seed flag unless you've modified the deployment commands from their default state
php artisan cloud:command "php artisan migrate --seed --force"

# Optional: Pre-populate a specific users on the fly instead of using the seeder
php artisan cloud:command "php artisan tinker --execute=\"app(\App\Services\GistService::class)->syncUserGists('taylorotwell');\""

🧪 Testing

Test Structure

tests/
├── Feature/
│   ├── BlogControllerTest.php      # Route and controller tests
│   ├── GistManagementTest.php      # End-to-end gist operations
│   └── LivewireSearchTest.php      # Livewire component tests
├── Unit/
│   ├── GistServiceTest.php         # GitHub API service tests
│   ├── GistModelTest.php           # Model methods and scopes
│   └── JobsTest.php                # Queue job testing
└── Mocks/
    └── GitHubApiResponses.php      # Mock API responses

Running Tests

# Run all tests
php artisan test

# Run with coverage
php artisan test --coverage

# Run specific test suite
php artisan test --testsuite=Feature
php artisan test --testsuite=Unit

# Run specific test file
php artisan test tests/Feature/BlogControllerTest.php

Test Categories

1. Unit Tests

GistServiceTest.php:

  • ✅ Fetch user gists from GitHub API
  • ✅ Handle API rate limiting and errors
  • ✅ Parse gist data correctly
  • ✅ Cache gist responses
  • ✅ Sync individual gist content

GistModelTest.php:

  • ✅ Model relationships and attributes
  • ✅ Cache expiration logic
  • ✅ Query scopes (forUsername, recent)
  • ✅ Data casting and mutators

JobsTest.php:

  • ✅ RefreshUserGists job execution
  • ✅ Queue job retries and failures
  • ✅ Background processing workflow

2. Feature Tests

BlogControllerTest.php:

  • ✅ Homepage displays recent gists and examples
  • ✅ User blog page loads and caches gists
  • ✅ Individual gist page displays content
  • ✅ Handles non-existent users gracefully
  • ✅ Queue dispatch for cache refresh

GistManagementTest.php:

  • ✅ End-to-end gist fetching and storage
  • ✅ Cache invalidation workflows
  • ✅ Database transaction integrity
  • ✅ API error handling

LivewireSearchTest.php:

  • ✅ Real-time search functionality
  • ✅ Language filtering
  • ✅ Component state management
  • ✅ DOM updates and interactions

3. HTTP Tests with Mocked APIs

GitHub API Mocking:

// Mock successful gist list response
Http::fake([
    'api.github.com/users/*/gists' => Http::response($this->mockGistsList(), 200),
    'api.github.com/gists/*' => Http::response($this->mockSingleGist(), 200),
]);

Database Testing

# Use in-memory SQLite for speed
# Configured in phpunit.xml

# Test database migrations
php artisan test --testsuite=Feature tests/Feature/DatabaseTest.php

Performance Testing

# Test API response times
php artisan test tests/Performance/ApiPerformanceTest.php

# Test database query efficiency
php artisan test tests/Performance/DatabasePerformanceTest.php

📊 Key Testing Scenarios

1. GitHub API Integration

  • Mock GitHub API responses for consistent testing
  • Test rate limiting and error handling
  • Verify data parsing and storage

2. Caching Strategy

  • Test cache hits and misses
  • Verify cache expiration logic
  • Test background refresh jobs

3. User Experience

  • Test loading states for new users
  • Verify search and filtering functionality
  • Test responsive design elements

4. Error Handling

  • Non-existent GitHub users
  • API rate limiting scenarios
  • Network connectivity issues
  • Invalid gist data

🔍 Code Quality

# Static analysis with PHPStan
./vendor/bin/phpstan analyse

📈 Performance Monitoring

Key Metrics to Monitor

  1. GitHub API Usage: Rate limiting and response times
  2. Database Performance: Query count and execution time
  3. Cache Hit Ratio: Redis performance and efficiency
  4. Queue Processing: Job completion rates and delays

Laravel Cloud Monitoring

  • Built-in performance monitoring
  • Database query analysis
  • Queue job tracking
  • Error logging and alerts

Troubleshooting

Common Issues

GitHub API Rate Limiting:

# Check current rate limit status
curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/rate_limit

Queue Jobs Not Processing:

# Restart queue workers
php artisan queue:restart

# Check failed jobs
php artisan queue:failed

Cache Issues:

# Clear application cache
php artisan cache:clear

# Clear config cache
php artisan config:clear

📝 API Endpoints

  • GET / - Homepage with recent gists and examples
  • GET /{username} - User's gist blog
  • GET /{username}/{gistId} - Individual gist view

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Write tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request

📄 License

This project is open-sourced software licensed under the MIT license.

🔗 Links

Roadmap

  • Ability to claim and customize your own blog page
  • Ability to hide certain Gists

Built with ❤️ from 🇨🇦