Installation

Media Library Pro is a paid package served from a private Composer repository. Your purchase email holds a licence key; your username is the email you bought with.

Add the repository

composer config repositories.media-library composer https://packages.hoceine.com

Add your licence

composer config http-basic.packages.hoceine.com you@example.com YOUR-LICENCE-KEY

This writes to the project's auth.json. Keep that file out of git, or add --global to store the credentials once for every project on your machine.

Require the package

composer require hoceineel/filament-media-library-pro

Run the installer

php artisan media-library:install

The installer does five things:

1. Publishes config/filament-media-library.php.
2. Publishes Spatie's config/media-library.php if you do not have one yet.
3. Publishes Spatie's create_media_table migration if your app has none yet.
4. Asks Run the migrations now? and runs php artisan migrate if you accept. The library's own tables load from the package, so they are migrated with the rest.
5. Runs storage:link when a public disk exists and public/storage does not.

It finishes by printing the next steps. Pass --force to overwrite a config file you published earlier. In a script, add --no-interaction so the migration prompt takes its default and does not wait for input.

Custom key types

If your users or tenants use UUID or ULID keys, set key_types in the published config before you migrate. Answer no to the migration prompt, edit the config, then run php artisan migrate.

Register the plugin

Add the plugin to your panel provider:

use Hoceineel\FilamentMediaLibrary\FilamentMediaLibraryPlugin;
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(
            FilamentMediaLibraryPlugin::make()
                ->navigationGroup('Content')
                ->navigationCountBadge()
        );
}

This adds the Media library page to the panel at /media-library under your panel path. If the panel uses Filament tenancy, the library scopes itself to the current tenant with no extra call. For stancl/tenancy or your own tenant lookup, add ->tenancy() and ->resolveTenantUsing(). See Tenancy and the plugin reference.

Publish the assets

php artisan filament:assets

Run this again after every update.

Run a queue worker

Thumbnails are generated while the upload request runs, so new files appear at once. Larger conversions, such as the preview size, are queued. Keep a worker running:

php artisan queue:work

Schedule the cleanup

In routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('media-library:prune')->daily();

The command deletes trash older than 30 days and abandoned upload chunks. See Commands.

Check it works

1. Open the panel and click Media library in the navigation.
2. Drop an image onto the page. It should upload and open in the details panel.
3. Run php artisan route:list --name=media-library and confirm the upload routes are listed.

If a thumbnail stays blank, check that the queue worker is running and that storage:link has been run. For more, see Troubleshooting. To build your first form field, continue with the Quick Start.

Deploying

Servers and CI need the same credentials. Either commit nothing and set them per environment:

composer config --global http-basic.packages.hoceine.com you@example.com YOUR-LICENCE-KEY

or provide them as JSON in the COMPOSER_AUTH environment variable:

COMPOSER_AUTH='{"http-basic":{"packages.hoceine.com":{"username":"you@example.com","password":"YOUR-LICENCE-KEY"}}}'

On Laravel Forge, add them in the server's or site's Composer package authentication settings. After each deploy, run php artisan migrate --force and php artisan filament:assets, and restart your queue workers.

Updates

Your licence includes updates for its update window. Releases published after the window ends stay hidden until you renew; versions you already have keep installing.

Publishing files

php artisan vendor:publish --tag=filament-media-library-config
php artisan vendor:publish --tag=filament-media-library-translations
php artisan vendor:publish --tag=filament-media-library-views

English and Arabic ship in the box. See Translations.