PHPackages                             tomatophp/filament-cms-github - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. tomatophp/filament-cms-github

ActiveLibrary[API Development](/categories/api)

tomatophp/filament-cms-github
=============================

Github integration to import your repo docs README files as a docs on markdown format to TomatoPHP CMS

v4.0.0(8mo ago)00[4 PRs](https://github.com/tomatophp/filament-cms-github/pulls)MITPHPPHP ^8.2|^8.3|^8.4CI passing

Since Oct 9Pushed 1w agoCompare

[ Source](https://github.com/tomatophp/filament-cms-github)[ Packagist](https://packagist.org/packages/tomatophp/filament-cms-github)[ GitHub Sponsors](https://github.com/3x1io)[ RSS](/packages/tomatophp-filament-cms-github/feed)WikiDiscussions master Synced today

READMEChangelog (1)Dependencies (14)Versions (9)Used By (0)

[![Screenshot](https://raw.githubusercontent.com/tomatophp/filament-cms-github/master/arts/fadymondy-tomato-cms-github.jpg)](https://raw.githubusercontent.com/tomatophp/filament-cms-github/master/arts/fadymondy-tomato-cms-github.jpg)

Filament CMS GitHub Integration
===============================

[](#filament-cms-github-integration)

[![Latest Stable Version](https://camo.githubusercontent.com/5f2793ce39eefc6b4cd676a838dde7ec5bf17fff483e1ce5545fc5c45e3372fc/68747470733a2f2f706f7365722e707567782e6f72672f746f6d61746f7068702f66696c616d656e742d636d732d6769746875622f76657273696f6e2e737667)](https://packagist.org/packages/tomatophp/filament-cms-github)[![License](https://camo.githubusercontent.com/16cd6eac28a4799cc1d4263bd3d442f48e680d5416aea0baafe94da09b28e10e/68747470733a2f2f706f7365722e707567782e6f72672f746f6d61746f7068702f66696c616d656e742d636d732d6769746875622f6c6963656e73652e737667)](https://packagist.org/packages/tomatophp/filament-cms-github)[![Downloads](https://camo.githubusercontent.com/9ad7e27d87742cef5116235801cc151006b9703b98f3f813897d73f10603ec61/68747470733a2f2f706f7365722e707567782e6f72672f746f6d61746f7068702f66696c616d656e742d636d732d6769746875622f642f746f74616c2e737667)](https://packagist.org/packages/tomatophp/filament-cms-github)[![Dependabot Updates](https://github.com/tomatophp/filament-cms-github/actions/workflows/dependabot/dependabot-updates/badge.svg)](https://github.com/tomatophp/filament-cms-github/actions/workflows/dependabot/dependabot-updates)[![PHP Code Styling](https://github.com/tomatophp/filament-cms-github/actions/workflows/fix-php-code-styling.yml/badge.svg)](https://github.com/tomatophp/filament-cms-github/actions/workflows/fix-php-code-styling.yml)[![Tests](https://github.com/tomatophp/filament-cms-github/actions/workflows/tests.yml/badge.svg)](https://github.com/tomatophp/filament-cms-github/actions/workflows/tests.yml)

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

[](#screenshot)

[![Import Action](https://raw.githubusercontent.com/tomatophp/filament-cms-github/master/arts/import.png)](https://raw.githubusercontent.com/tomatophp/filament-cms-github/master/arts/import.png)

Features
--------

[](#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
------------

[](#installation)

Install the package via composer:

```
composer require tomatophp/filament-cms-github
```

Run the installation command:

```
php artisan filament-cms-github:install
```

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

```
use TomatoPHP\FilamentCmsGithub\FilamentCmsGithubPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(FilamentCmsGithubPlugin::make());
}
```

Requirements
------------

[](#requirements)

- PHP 8.2 or higher
- Laravel 10.x or 11.x
- Filament 3.x
- TomatoPHP CMS 4.x

Configuration
-------------

[](#configuration)

### Queue Setup

[](#queue-setup)

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

```
# Run queue worker
php artisan queue:work
```

### Post Type Configuration

[](#post-type-configuration)

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

Usage
-----

[](#usage)

### Import Single Repository

[](#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:**

```
URL: https://github.com/tomatophp/filament-cms
Redirect: /posts

```

### Import Multiple Repositories

[](#import-multiple-repositories)

You can import multiple repositories at once:

```
URL                                          | Redirect URL
-------------------------------------------- | ------------
https://github.com/tomatophp/filament-cms   | /cms
https://github.com/tomatophp/filament-alerts| /alerts
https://github.com/tomatophp/filament-users | /users

```

### Refresh All Repositories

[](#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

[](#programmatic-usage)

#### Import Repository

[](#import-repository)

```
use TomatoPHP\FilamentCmsGithub\Services\GitHubService;

$service = app(GitHubService::class);

$post = $service->importRepository(
    url: 'https://github.com/tomatophp/filament-cms',
    userId: auth()->id(),
    userType: get_class(auth()->user())
);
```

#### Refresh Existing Post

[](#refresh-existing-post)

```
use TomatoPHP\FilamentCmsGithub\Services\GitHubService;
use TomatoPHP\FilamentCms\Models\Post;

$service = app(GitHubService::class);
$post = Post::find(1);

$success = $service->refreshPost($post);
```

#### Refresh All Posts

[](#refresh-all-posts)

```
use TomatoPHP\FilamentCmsGithub\Services\GitHubService;

$service = app(GitHubService::class);
$count = $service->refreshAllPosts(); // Returns number of posts refreshed
```

API Reference
-------------

[](#api-reference)

### GitHubService

[](#githubservice)

The main service class for GitHub operations.

#### `extractRepoFromUrl(string $url): string`

[](#extractrepofromurlstring-url-string)

Extracts repository name from GitHub URL.

```
$repo = $service->extractRepoFromUrl('https://github.com/tomatophp/filament-cms');
// Returns: 'tomatophp/filament-cms'
```

#### `fetchRepoData(string $repo): ?array`

[](#fetchrepodatastring-repo-array)

Fetches repository data from GitHub API.

```
$data = $service->fetchRepoData('tomatophp/filament-cms');
// Returns array with: id, name, full_name, description, stargazers_count, etc.
```

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

[](#fetchreadmestring-repo-string-branch--main-string)

Fetches README content from repository.

```
$readme = $service->fetchReadme('tomatophp/filament-cms', 'master');
// Returns: markdown content as string
```

#### `fetchPackagistData(string $packageName): ?array`

[](#fetchpackagistdatastring-packagename-array)

Fetches package data from Packagist.

```
$data = $service->fetchPackagistData('tomatophp/filament-cms');
// Returns array with downloads, versions, keywords, etc.
```

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

[](#importrepositorystring-url-int-userid--null-string-usertype--null-post)

Imports a complete repository as a post.

```
$post = $service->importRepository(
    url: 'https://github.com/tomatophp/filament-cms',
    userId: 1,
    userType: 'App\\Models\\User'
);
```

#### `refreshPost(Post $post): bool`

[](#refreshpostpost-post-bool)

Refreshes an existing post with latest GitHub data.

```
$success = $service->refreshPost($post);
```

#### `refreshAllPosts(): int`

[](#refreshallposts-int)

Refreshes all posts of type 'open-source' with meta\_url.

```
$count = $service->refreshAllPosts();
```

### Filament Actions

[](#filament-actions)

#### GithubImportAction

[](#githubimportaction)

Provides a Filament action for importing repositories.

```
use TomatoPHP\FilamentCmsGithub\Filament\Actions\GithubImportAction;

// In your resource
protected function getHeaderActions(): array
{
    return [
        GithubImportAction::make(),
    ];
}
```

#### GithubRefreshAction

[](#githubrefreshaction)

Provides a Filament action for refreshing all repositories.

```
use TomatoPHP\FilamentCmsGithub\Filament\Actions\GithubRefreshAction;

protected function getHeaderActions(): array
{
    return [
        GithubRefreshAction::make(),
    ];
}
```

Data Structure
--------------

[](#data-structure)

### Post Fields

[](#post-fields)

Imported repositories are saved with the following structure:

```
[
    'title' => ['en' => 'Repository Name', 'ar' => 'Repository Name'],
    'slug' => 'repository-name',
    'body' => ['en' => '# README content...', 'ar' => '# README content...'],
    'short_description' => ['en' => 'Description', 'ar' => 'Description'],
    'keywords' => ['en' => 'keyword1,keyword2', 'ar' => 'keyword1,keyword2'],
    'type' => 'open-source',
    'meta_url' => 'https://github.com/owner/repo',
    'is_published' => true,
    'published_at' => now(),
]
```

### Meta Fields

[](#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

[](#accessing-meta-fields)

```
$post = Post::find(1);

// Get star count
$stars = $post->meta('github_starts');

// Get total downloads
$downloads = $post->meta('downloads_total');
```

Jobs
----

[](#jobs)

### GitHubMetaGetterJob

[](#githubmetagetterjob)

Handles importing a single repository in the background.

```
use TomatoPHP\FilamentCmsGithub\Jobs\GitHubMetaGetterJob;

dispatch(new GitHubMetaGetterJob(
    url: 'https://github.com/tomatophp/filament-cms',
    redirect: '/posts',
    userId: auth()->id(),
    userType: get_class(auth()->user()),
    panel: 'admin'
));
```

### GitHubMetaRefreshJob

[](#githubmetarefreshjob)

Handles refreshing all repositories in the background.

```
use TomatoPHP\FilamentCmsGithub\Jobs\GitHubMetaRefreshJob;

dispatch(new GitHubMetaRefreshJob);
```

Events
------

[](#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
-------------

[](#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
-------

[](#testing)

The package includes comprehensive test coverage:

```
# Run tests
composer test

# Run tests with coverage
composer test-coverage

# Run static analysis
composer analyse

# Format code
composer format
```

### Test Structure

[](#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
--------------

[](#publish-assets)

### Config File

[](#config-file)

```
php artisan vendor:publish --tag="filament-cms-github-config"
```

### Views

[](#views)

```
php artisan vendor:publish --tag="filament-cms-github-views"
```

### Translations

[](#translations)

```
php artisan vendor:publish --tag="filament-cms-github-lang"
```

### Migrations

[](#migrations)

```
php artisan vendor:publish --tag="filament-cms-github-migrations"
```

Troubleshooting
---------------

[](#troubleshooting)

### Queue Not Processing

[](#queue-not-processing)

Make sure your queue worker is running:

```
php artisan queue:work
```

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

```
QUEUE_CONNECTION=sync
```

### GitHub API Rate Limits

[](#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

[](#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
--------------

[](#advanced-usage)

### Custom Post Processing

[](#custom-post-processing)

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

```
use TomatoPHP\FilamentCms\Events\PostCreated;
use Illuminate\Support\Facades\Event;

Event::listen(PostCreated::class, function ($event) {
    $post = $event->model;

    // Custom processing here
    if ($post->type === 'open-source') {
        // Do something with imported repository
    }
});
```

### Custom Notification Handling

[](#custom-notification-handling)

```
use Illuminate\Support\Facades\Notification;
use TomatoPHP\FilamentCmsGithub\Jobs\GitHubMetaGetterJob;

class CustomNotificationHandler
{
    public function handle(GitHubMetaGetterJob $job)
    {
        // Custom notification logic
    }
}
```

Contributing
------------

[](#contributing)

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

### Development Setup

[](#development-setup)

```
# Clone the repository
git clone https://github.com/tomatophp/filament-cms-github.git

# Install dependencies
composer install

# Run tests
composer test
```

Testing
-------

[](#testing-1)

if you like to run `PEST` testing just use this command

```
composer test
```

Code Style
----------

[](#code-style)

if you like to fix the code style, just use this command

```
composer format
```

PHPStan
-------

[](#phpstan)

if you like to check the code by `PHPStan` just use this command

```
composer analyse
```

Other Filament Packages
-----------------------

[](#other-filament-packages)

Check out our [Awesome TomatoPHP](https://github.com/tomatophp/awesome)

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance80

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity58

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 62.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

268d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/2147eb2fca7ab5f0124d0fafd88ba2d2a5dfa3a0036fb8872d1084b7cba29366?d=identicon)[fadymondy](/maintainers/fadymondy)

---

Top Contributors

[![fadymondy](https://avatars.githubusercontent.com/u/11937812?v=4)](https://github.com/fadymondy "fadymondy (10 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (4 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (2 commits)")

---

Tags

phplaravelgithubintegrationfilamentphptomatophpfilament cmsgithub-readmegithub-docs-import

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/tomatophp-filament-cms-github/health.svg)

```
[![Health](https://phpackages.com/badges/tomatophp-filament-cms-github/health.svg)](https://phpackages.com/packages/tomatophp-filament-cms-github)
```

###  Alternatives

[tomatophp/filament-cms

Full CMS System with support of importing integrations and multi meta functions

12012.5k4](/packages/tomatophp-filament-cms)[tomatophp/filament-api

Generate APIs from your filament resource using single line of code

537.3k1](/packages/tomatophp-filament-api)[tomatophp/filament-tenancy

Tenancy multi-database integration for FilamentPHP

624.4k](/packages/tomatophp-filament-tenancy)[tomatophp/filament-ecommerce

Build your own ecommerce store with FilamentPHP with the Power of Tomato CMS Builder

984.5k1](/packages/tomatophp-filament-ecommerce)[tomatophp/filament-fcm

Firebase Cloud Messaging integration to Native FilamentPHP Notification Package

202.2k1](/packages/tomatophp-filament-fcm)[octw/aramex

A Library to integrate with Aramex APIs

2927.7k](/packages/octw-aramex)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)