Github Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require graham-campbell/github:^13.1

Register the service provider in config/app.php (if not using auto-discovery):

'providers' => [
    GrahamCampbell\GitHub\GitHubServiceProvider::class,
],

Publish the config:

php artisan vendor:publish --provider="GrahamCampbell\GitHub\GitHubServiceProvider"

2. Configure GitHub Connection: Edit config/github.php to define your connection (e.g., main or alternative) with authentication method (token, application, jwt, private, or none). Example:

   'connections' => [
       'main' => [
           'auth' => [
               'method' => 'token',
               'token' => env('GITHUB_TOKEN'),
           ],
       ],
   ],
   

3. First Use Case: Fetch the authenticated user’s organizations:

   use GrahamCampbell\GitHub\Facades\GitHub;
   
   $organizations = GitHub::me()->organizations();
   

Implementation Patterns

Core Workflows

1. Facade-Based Usage: Leverage the GitHub facade for concise syntax:

   // Fetch a repo
   $repo = GitHub::repo()->show('owner', 'repo-name');
   
   // List issues
   $issues = GitHub::issues()->all('owner', 'repo-name');
   

2. Connection Switching: Use named connections dynamically:

   // Use 'alternative' connection
   $emails = GitHub::connection('alternative')->me()->emails()->all();
   

3. Dependency Injection: Inject GitHubManager into services for type safety:

   use GrahamCampbell\GitHub\GitHubManager;
   
   class GitHubService {
       public function __construct(private GitHubManager $github) {}
   
       public function fetchIssues() {
           return $this->github->issues()->all('owner', 'repo-name');
       }
   }
   

4. Caching Responses: Enable HTTP caching in config/github.php:

   'cache' => [
       'enabled' => true,
       'driver' => 'illuminate',
       'prefix' => 'github_',
   ],
   

   Cache TTLs are managed automatically (default: 9m59s for JWT tokens).

Integration Tips

1. Environment Variables: Store sensitive credentials (e.g., GITHUB_TOKEN) in .env:

   GITHUB_TOKEN=your_github_token_here
   

2. Error Handling: Wrap API calls in try-catch blocks:

   try {
       $repo = GitHub::repo()->show('owner', 'repo-name');
   } catch (\Github\Exception\RuntimeException $e) {
       Log::error('GitHub API error: ' . $e->getMessage());
   }
   

3. Pagination: Use the all() method for paginated results:

   $allIssues = GitHub::issues()->all('owner', 'repo-name');
   

4. Webhooks: Combine with Laravel’s Http client for webhook validation:

   $payload = request()->json()->all();
   $event = GitHub::webhook()->validate($payload, request()->header('X-Hub-Signature-256'));
   

Gotchas and Tips

Pitfalls

1. Authentication Methods:

   • Deprecated Methods: Avoid none or application for production (use token or private key).
   • JWT Tokens: Expire after 9m59s (not 10m) to avoid cache staleness.

2. Case-Sensitive Filesystems: Ensure filesystem paths in config/filesystems.php match the case of your actual storage.

3. Cache Quirks:

   • TTL Overrides: Cache TTLs are capped to avoid excessive storage. Override via config/github.php:

     'cache' => [
         'ttl' => 3600, // 1 hour
     ],
     

   • Driver Compatibility: Only illuminate cache driver is officially supported.

4. Rate Limiting: GitHub enforces rate limits. Handle 403 errors gracefully:

   if ($e->getCode() === 403) {
       // Retry or notify admin
   }
   

Debugging Tips

1. Enable Debugging: Set GITHUB_DEBUG=true in .env to log API requests/responses.

2. Inspect Raw Responses: Use the underlying Github\Client methods:

   $response = GitHub::connection()->raw('GET', '/user');
   

3. Common Errors:

   • InvalidArgumentException: Check connection config (e.g., missing token).
   • RuntimeException: Validate API endpoint syntax (e.g., repo()->show() requires owner/repo).

Extension Points

1. Custom Authenticators: Extend GrahamCampbell\GitHub\Auth\Authenticator for custom OAuth flows.

2. Middleware: Add HTTP middleware to the Github\Client via config/github.php:

   'connections' => [
       'main' => [
           'middleware' => [
               \App\Http\Middleware\GitHubLogging::class,
           ],
       ],
   ],
   

3. Event Listeners: Listen for GitHub webhook events:

   GitHub::webhook()->listen('push', function ($payload) {
       // Handle push event
   });
   

4. Testing: Use GitHub::shouldReceive() in PHPUnit:

   GitHub::shouldReceive('repo()->show')
          ->once()
          ->andReturn(new \Github\Result\Repository());
   

---