README

Filament Satis

A Filament plugin for managing private Composer repositories powered by Satis.

Features

• Package Management — Add and manage Composer & GitHub package sources with CRUD operations
• Token-Based Auth — Secure access with per-token package scoping
• Dev Packages — Mark packages as development-only with is_dev flag
• Version Tracking — Automatic tracking of package releases synced from Satis builds
• Download Statistics — Per-version download tracking and analytics
• Dependency Mapping — Public/private dependency classification from package releases
• Multi-Tenancy — Tenant-isolated data with configurable foreign keys
• Credential Validation — Verify package accessibility with tracked validation timestamps
• Intelligent Validation — Timestamp-based comparison to skip unnecessary rebuilds
• Auth.json Support — Automatic auth.json generation for authenticated Composer builds
• Credential Sanitization — Remove transport-options from Satis JSON files to prevent credential leaks
• GitHub Webhooks — Auto-rebuild on push, release and create events with HMAC-SHA256 signature validation
• Per-Resource Config — Customize navigation, icons, slugs, clusters, and visibility per resource
• Global Search — Search packages, tokens, releases, and dependencies from the global search bar
• Bilingual — English and Brazilian Portuguese translations included
• Laravel Boost — AI guidelines and skills for assisted development

Version Compatibility

Requirements

• PHP ^8.3
• Laravel ^11.28
• Filament ^5.0
• jeffersongoncalves/laravel-satis ^1.0

Installation

You can install the package via composer:

1. Require the packages

composer require jeffersongoncalves/filament-satis

This will automatically install jeffersongoncalves/laravel-satis as a dependency.

2. Publish and run migrations

php artisan vendor:publish --tag="satis-migrations"
php artisan migrate

3. Publish the config (optional)

php artisan vendor:publish --tag="filament-satis-config"
php artisan vendor:publish --tag="satis-config"

Quick Start

1. Register the plugin

Add the plugin to your Filament panel provider:

use JeffersonGoncalves\FilamentSatis\FilamentSatisPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentSatisPlugin::make(),
        ]);
}

2. Create packages and tokens

1. Navigate to Satis > Packages in the admin panel
2. Add a package with its repository URL
3. Navigate to Satis > Tokens and create an authentication token
4. Associate the token with the packages it should access

3. Build the repository

php artisan satis:build

4. Configure your client

In your client project's composer.json:

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://your-app.com/satis"
        }
    ]
}

Authenticate with the token:

composer config http-basic.your-app.com token "your-64-char-token-here"

Multi-Tenancy

Enable tenant isolation for packages, tokens, and builds:

use JeffersonGoncalves\FilamentSatis\FilamentSatisPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentSatisPlugin::make()
                ->tenancy(
                    enabled: true,
                    model: \App\Models\Team::class,
                    foreignKey: 'team_id'
                ),
        ]);
}

The plugin automatically:

• Sets the satis tenancy configuration during register()
• Configures the tenant resolver using filament()->getTenant() during boot()
• Scopes all queries and auto-sets the foreign key on creation

Configuration

Filament Plugin Config

The config/filament-satis.php file provides per-resource customization:

return [
    // Shared navigation group for all resources
    'navigation_group' => 'Satis',

    // Per-resource configuration
    'package_resource' => [
        'cluster' => null,                        // Filament cluster class
        'should_register_navigation' => true,     // Show in sidebar
        'navigation_icon' => 'heroicon-o-cube',   // Heroicon name
        'navigation_sort' => 1,                   // Sort order
        'slug' => 'satis/packages',               // URL slug
    ],

    'token_resource' => [
        'cluster' => null,
        'should_register_navigation' => true,
        'navigation_icon' => 'heroicon-o-key',
        'navigation_sort' => 2,
        'slug' => 'satis/tokens',
    ],

    'package_release_resource' => [
        'cluster' => null,
        'should_register_navigation' => true,
        'navigation_icon' => 'heroicon-o-tag',
        'navigation_sort' => 3,
        'slug' => 'satis/package-releases',
    ],

    'package_download_resource' => [
        'cluster' => null,
        'should_register_navigation' => true,
        'navigation_icon' => 'heroicon-o-arrow-down-tray',
        'navigation_sort' => 4,
        'slug' => 'satis/package-downloads',
    ],

    'dependency_resource' => [
        'cluster' => null,
        'should_register_navigation' => true,
        'navigation_icon' => 'heroicon-o-link',
        'navigation_sort' => 5,
        'slug' => 'satis/dependencies',
    ],
];

Laravel Satis Config

The config/satis.php file configures the core backend:

return [
    // Multi-tenancy
    'tenancy' => [
        'enabled' => false,
        'model' => null,
        'foreign_key' => null,
        'ownership_relationship' => null,
        'resolver' => null,
    ],

    // Database table prefix (set to null for unprefixed tables)
    'table_prefix' => 'satis_',

    // Override default model classes
    'models' => [
        'package' => \JeffersonGoncalves\LaravelSatis\Models\Package::class,
        'token' => \JeffersonGoncalves\LaravelSatis\Models\Token::class,
        // ...
    ],

    // Storage for Satis builds
    'storage_disk' => 'local',
    'storage_path' => 'satis',

    // Satis build configuration
    'satis' => [
        'name' => 'my/repository',
        'output_html' => false,
        'archive' => ['directory' => 'archives', 'skip_dev' => true],
        'minimum_stability' => 'stable',
        'secure_http' => false,
    ],

    // Queue settings
    'queue' => [
        'connection' => null,
        'queue_name' => null,
        'timeout' => 86400, // 24 hours
    ],

    // Scheduled command frequencies
    'schedule' => [
        'build' => 'weekly',
        'token_build' => 'weekly',
        'validate' => 'hourly',
        'sanitize' => 'daily',
        'dependencies' => 'weekly',
    ],

    // Auth guard and provider
    'auth' => ['guard' => 'satis-token', 'provider' => 'satis-tokens'],

    // Route prefixes and middleware (set composer_prefix to null for no prefix)
    'routes' => [
        'api_prefix' => 'api/satis',
        'composer_prefix' => 'satis',
        'middleware' => ['api'],
    ],
];

Resources

The plugin registers 5 Filament resources:

Relation Managers

• PackageResource includes ReleasesRelationManager and DownloadsRelationManager
• DependencyResource includes PackageReleasesRelationManager

Customization Examples

Hide a resource from navigation

// config/filament-satis.php
'package_download_resource' => [
    'should_register_navigation' => false,
    // ...
],

Change navigation icons

'package_resource' => [
    'navigation_icon' => 'heroicon-o-archive-box',
    // ...
],

Group resources in a cluster

'package_resource' => [
    'cluster' => \App\Filament\Clusters\SatisCluster::class,
    // ...
],
'token_resource' => [
    'cluster' => \App\Filament\Clusters\SatisCluster::class,
    // ...
],

Change the navigation group

'navigation_group' => 'Package Management',

Override model classes

// config/satis.php
'models' => [
    'package' => \App\Models\CustomPackage::class,
],

Custom models must extend the base models from the package.

Translations

The plugin includes English and Brazilian Portuguese translations.

Publish translations

php artisan vendor:publish --tag="filament-satis-translations"

Translation files use the filament-satis:: namespace:

__('filament-satis::package.navigation_label')
__('filament-satis::package.fields.name')
__('filament-satis::general.created_at')

Commands

GitHub Webhooks

Each package auto-generates a webhook_secret and reference. Configure your GitHub webhook:

• URL: https://your-app.com/api/satis/webhooks/github/{reference}
• Secret: The webhook_secret from the package edit form
• Events: Push, Release, Create
• Content Type: application/json

The webhook handler:

1. Validates the package is a GitHub type
2. Filters supported events (push, release, create)
3. Verifies HMAC-SHA256 signature when a secret is configured
4. Dispatches tenant and token rebuilds

Laravel Boost Integration

This package includes Laravel Boost guidelines and skills for AI-assisted development. When Boost is installed in your project, run:

php artisan boost:install

The plugin's AI guidelines and skills will be automatically detected and available to your coding agent.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Jefferson Goncalves
• All Contributors

License

The MIT License (MIT). Please see License File for more information.