filament-cms-github

Filament CMS GitHub Integration

GitHub integration for TomatoPHP CMS that automatically imports and synchronizes GitHub repository documentation (README files) as posts in your CMS. Perfect for maintaining documentation sites, portfolio showcases, or open-source project listings.

Screenshot

Features

• 🚀 Automatic Import - Import GitHub repositories with a single click
• 📄 README Sync - Automatically fetches and converts README.md to post content
• 📊 GitHub Stats - Imports stars, forks, watchers, and issue counts
• 📦 Packagist Integration - Fetches download statistics for PHP packages
• 🔄 Bulk Refresh - Update all imported repositories at once
• 🎨 Avatar Images - Automatically downloads repository owner avatars
• 🏷️ Auto Tagging - Extracts keywords from Packagist data
• ⚡ Queue Support - Background processing for better performance
• 🔔 Notifications - User notifications on import success/failure
• 🧪 Full Test Coverage - 39 comprehensive tests

Installation

Install the package via composer:

Run the installation command:

Register the plugin in your Filament panel provider (/app/Providers/Filament/AdminPanelProvider.php):

The import action lives in the posts page "Content Import" group, so enable it on the CMS plugin:

Requirements

Package version	Filament CMS	Filament	Laravel	PHP
5.x	5.x	5.x	12.x, 13.x	8.2+
4.x	4.x	4.x	11.x, 12.x	8.2+

Configuration

Queue Setup

This package dispatches jobs to the queue for better performance. Make sure your queue is configured:

Post Type Configuration

Imported repositories are saved as posts with type open-source. You can customize this in your CMS configuration.

Usage

Import Single Repository

1. Navigate to your CMS Posts page in Filament
2. Click the "Github Import" action button
3. Enter repository URL(s) and redirect path(s)
4. Click submit

Example:

Import Multiple Repositories

You can import multiple repositories at once:

Refresh All Repositories

To update all previously imported repositories with latest data:

1. Use the "Refresh Github Links" action
2. All posts with type = 'open-source' and a meta_url will be updated

Programmatic Usage

Import Repository

Refresh Existing Post

Refresh All Posts

API Reference

GitHubService

The main service class for GitHub operations.

extractRepoFromUrl(string $url): string

Extracts repository name from GitHub URL.

fetchRepoData(string $repo): ?array

Fetches repository data from GitHub API.

fetchReadme(string $repo, string $branch = 'main'): ?string

Fetches README content from repository.

fetchPackagistData(string $packageName): ?array

Fetches package data from Packagist.

importRepository(string $url, ?int $userId = null, ?string $userType = null): ?Post

Imports a complete repository as a post.

refreshPost(Post $post): bool

Refreshes an existing post with latest GitHub data.

refreshAllPosts(): int

Refreshes all posts of type 'open-source' with meta_url.

Filament Actions

GithubImportAction

Provides a Filament action for importing repositories.

GithubRefreshAction

Provides a Filament action for refreshing all repositories.

Data Structure

Post Fields

Imported repositories are saved with the following structure:

Meta Fields

GitHub statistics are stored as meta fields:

• github_starts - Star count
• github_watchers - Watcher count
• github_language - Primary language
• github_forks - Fork count
• github_open_issues - Open issue count
• github_default_branch - Default branch name
• github_docs - Homepage/documentation URL
• downloads_total - Total Packagist downloads (if available)
• downloads_monthly - Monthly downloads
• downloads_daily - Daily downloads

Accessing Meta Fields

Jobs

GitHubMetaGetterJob

Handles importing a single repository in the background.

GitHubMetaRefreshJob

Handles refreshing all repositories in the background.

Events

The package dispatches the following events:

• TomatoPHP\FilamentCms\Events\PostCreated - When a repository is imported
• TomatoPHP\FilamentCms\Events\PostUpdated - When a repository is refreshed

Notifications

Users receive notifications for:

• Import Success - Repository imported successfully with link to view post
• Import Failure - Repository import failed with error details
• Refresh Success - All repositories refreshed successfully

Testing

The package includes comprehensive test coverage:

Test Structure

• GitHubServiceTest (17 tests) - Tests all service methods
• GitHubActionsTest (13 tests) - Tests Filament actions
• GitHubJobsTest (7 tests) - Tests job execution
• PluginTest (1 test) - Tests plugin registration

Publish Assets

Config File

Views

Translations

Migrations

Troubleshooting

Queue Not Processing

Make sure your queue worker is running:

For development, you can use sync driver in .env:

GitHub API Rate Limits

GitHub API has rate limits. For authenticated requests (recommended), generate a personal access token and configure it in your application.

README Not Found

The package tries multiple branch names automatically:

• main
• master
• Default branch from GitHub API

If README is not found, the post will be created with empty body content.

Advanced Usage

Custom Post Processing

You can listen to the PostCreated event to perform custom processing:

Custom Notification Handling

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Setup