Filament Sanchaya

A file manager and media picker for Laravel and Filament.

In Nepali, Sanchaya (सञ्चय) means the act of gathering or amassing something valuable over time. This package follows that idea: your files are gathered in one place, indexed in your database, and managed with a familiar Filament experience.

Requirements

• Filament ^5.0
• For filament v4 its not tested.

Installation

1. Install via Composer

composer require dp0/filament-sanchaya

2. Run the Interactive Installer

php artisan sanchaya:install

The installer will prompt you to:

• Publish config/filament-sanchaya.php
• Publish and run migrations
• Choose your default storage disk

3. Filament Custom Theme Requirement

If you do not have a custom theme configured for your Filament panel, generate one:

php artisan make:filament-theme

Add the package's views directory to your custom theme's main CSS file (usually resources/css/filament/admin/theme.css) using the @source directive. Adjust the relative path if your theme is in another directory:

@source "../../../../vendor/dp0/filament-sanchaya/resources/views";

Then make sure your panel actually uses that theme by pointing viteTheme() at it in your panel provider — otherwise your theme (and the package styles) will never be loaded:

public function panel(Panel $panel): Panel
{
    return $panel
        ->viteTheme('resources/css/filament/admin/theme.css')
        ->plugins([
            SanchayaPlugin::make(),
        ]);
}

Finally, compile your assets using your asset bundler:

npm run dev # or npm run build

Manual Publishing

php artisan vendor:publish --tag=sanchaya-config
php artisan vendor:publish --tag=sanchaya-migrations
php artisan vendor:publish --tag=sanchaya-views
php artisan migrate

Configuration

Edit config/filament-sanchaya.php after publishing.

return [
    // Eloquent model for file records
    'model' => \DP0\Sanchaya\Models\SanchayaFile::class,

    // Eloquent model for polymorphic attachments
    'attachment_model' => \DP0\Sanchaya\Models\SanchayaAttachment::class,

    // Gate policy for file operations. null = no authorization.
    'policy' => \DP0\Sanchaya\Policies\SanchayaFilePolicy::class,

    // true = soft deletes (recoverable); false = hard delete
    'soft_deletes' => true,

    'allowed_disks' => null,

    'default_disk' => env('SANCHAYA_DEFAULT_DISK', 'public'),

    'file' => [
        'max_file_size'       => 10240,  // KB — 10 MB
        'accepted_file_types' => [],     // e.g. ['image/*']
    ],

    'storage_quota' => null, // bytes; null = unlimited

    'actions' => [
        'download' => [
            'enabled' => true,
            'label' => 'Download',
            'icon' => 'heroicon-m-arrow-down-tray',
            'class' => \DP0\Sanchaya\Actions\DownloadAction::class,
        ],
        'create_folder' => [
            'enabled' => true,
            'label' => 'Create Folder',
            'icon' => 'heroicon-m-folder-plus',
            'class' => \DP0\Sanchaya\Actions\CreateFolderAction::class,
        ],
        'rename' => [
            'enabled' => true,
            'label' => 'Rename',
            'icon' => 'heroicon-m-pencil',
            'class' => \DP0\Sanchaya\Actions\RenameAction::class,
        ],
        'move' => [
            'enabled' => true,
            'label' => 'Move',
            'icon' => 'heroicon-m-arrow-right-circle',
            'class' => \DP0\Sanchaya\Actions\MoveAction::class,
        ],
        'copy' => [
            'enabled' => true,
            'label' => 'Copy',
            'icon' => 'heroicon-m-document-duplicate',
            'class' => \DP0\Sanchaya\Actions\CopyAction::class,
        ],
        'delete' => [
            'enabled' => true,
            'label' => 'Delete',
            'icon' => 'heroicon-m-trash',
            'class' => \DP0\Sanchaya\Actions\DeleteAction::class,
        ],
    ],

    'sanchaya_picker' => [
        'multiple' => false,
        'allowed_types' => [], // e.g. ['image']
        'max_files' => null,
    ],
];

Config Reference

Plugin Registration

Register in your Filament panel provider:

use DP0\Sanchaya\SanchayaPlugin;

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

Fluent Options

SanchayaPlugin::make()
    ->navigationLabel('Filament Sanchaya')
    ->navigationIcon('heroicon-o-folder')
    ->navigationGroup('Content')
    ->navigationSort(20);

The default sidebar label is Filament Sanchaya. Use navigationLabel('Media') if you want a shorter label, slug('media') to change the page path, or withoutNavigation() to hide its sidebar entry. The default slug is sanchaya.

Authorization & Policy

Sanchaya ships with SanchayaFilePolicy, which permits authenticated users by default. Register a restrictive policy for production access control.

// config/filament-sanchaya.php
'policy' => \App\Policies\MyFilePolicy::class,

File Manager & Bulk Actions

Register the plugin in your Filament panel to add the file manager. Its URL uses your panel's path followed by /sanchaya by default.

Trash Bin & Soft Deletes

When soft_deletes is enabled (the default), deleting files or folders marks their database records as deleted and keeps file contents on disk for restoration. The Trash sidebar entry is hidden when soft deletes are disabled.

Key Capabilities

• Dedicated Bin View: Access the Trash Bin directly from the sidebar. Shows all soft-deleted items on the current disk.
• One-Click Restore: Restore individual items from the context dropdown or select multiple items and click Restore Selected.
• Permanent Deletion: Delete individual or selected trashed items to remove stored file contents and database records. Deleting a folder also removes its nested files.
• Empty Trash: Purge all trashed files and folders across the selected disk with a single click.

// config/filament-sanchaya.php
'soft_deletes' => true, // Set to false to immediately force-delete files from disk

Permanent deletion cannot be undone. With soft_deletes set to false, the ordinary Delete action is permanent.

SanchayaPicker Form Field

The SanchayaPicker form component lets users pick existing files or upload new files directly inside any Filament Resource Form or Schema.

Add HasSanchayaFiles to the form's model to persist the selected attachments automatically. Chunked uploads and image manipulation are planned for the next release.

use DP0\Sanchaya\Forms\Components\SanchayaPicker;

Single File Attachment

SanchayaPicker::make('avatar')
    ->label('Avatar Image')
    ->saveInGroup('avatar')
    ->allowedTypes(['image']);

Multiple Files Gallery

SanchayaPicker::make('gallery')
    ->label('Product Gallery')
    ->multiple()
    ->maxFiles(8)
    ->saveInGroup('gallery')
    ->allowedTypes(['image'])
    ->uploadMaxFileSize(5120); // 5 MB upload limit

Method Reference

SanchayaColumn Table Column

Display polymorphic media files directly inside your Filament Table using SanchayaColumn. It automatically resolves images attached via HasSanchayaFiles.

use DP0\Sanchaya\Tables\Columns\SanchayaColumn;

Single Avatar Column

SanchayaColumn::make('avatar')
    ->label('User Avatar')
    ->sanchayaGroup('avatar')
    ->circular();

Stacked Multi-Image Gallery Column

SanchayaColumn::make('gallery')
    ->label('Images')
    ->sanchayaGroup('gallery')
    ->multiple()
    ->stacked()
    ->limit(3)
    ->limitedRemainingText();

Method Reference

SanchayaEntry Infolist Entry

Render attached media inside your Filament Infolists with group resolution.

use DP0\Sanchaya\Infolists\Components\SanchayaEntry;

Single & Multiple Infolist Entries

SanchayaEntry::make('avatar')
    ->label('User Photo')
    ->group('avatar')
    ->circular();

SanchayaEntry::make('documents')
    ->label('Project Files')
    ->group('documents')
    ->multiple();

HasSanchayaFiles Trait

Add the HasSanchayaFiles trait to any Eloquent model to enable polymorphic, grouped media attachments without altering your table schemas.

use DP0\Sanchaya\Traits\HasSanchayaFiles;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    use HasSanchayaFiles;
}

Reading Attachments

// Get Eloquent Collection of SanchayaFile in 'gallery' group
$gallery = $post->sanchayaFiles('gallery');

// Get first file in 'hero' group
$heroFile = $post->sanchayaFile('hero');

// Get public or temporary URL directly
$heroUrl = $post->sanchayaUrl('hero');

// Get array of file IDs
$ids = $post->sanchayaFileIds('gallery');

// Check if any files are attached
$hasAvatar = $post->hasSanchayaFiles('avatar');

Writing Attachments

// Attach single file
$post->attachSanchayaFile($fileId, 'avatar');

// Sync a group to an exact ordered list of IDs (removes missing, adds new)
$post->syncSanchayaFiles([12, 14, 19], 'gallery');

// Detach all files in a group
$post->detachSanchayaFiles('gallery');

// Detach a specific file
$post->detachSanchayaFile($fileId, 'gallery');

SanchayaFile & Metadata / SEO

The SanchayaFile Eloquent model represents every indexed file and directory in Sanchaya.

Metadata & SEO Properties

Core Accessors & Scopes

Database Schema

sanchaya_files

sanchaya_attachments

Built-in Actions

Every file management operation in Sanchaya is isolated into a dedicated action class, making it completely unit-testable and extensible.

Extensibility & Customization

Sanchaya resolves its main behavior from configuration, so production apps can replace the default Eloquent models, authorization policy, and file-operation action classes without editing package files.

Replace Models and Policy

Use custom models when you need extra casts, relationships, scopes, observers, or table names. Extend the package models so the file manager keeps the expected relationships and helpers.

// config/filament-sanchaya.php
'model' => \App\Models\MediaFile::class,
'attachment_model' => \App\Models\MediaAttachment::class,
'policy' => \App\Policies\MediaFilePolicy::class,

namespace App\Models;

use DP0\Sanchaya\Models\SanchayaFile;

class MediaFile extends SanchayaFile
{
    protected $table = 'sanchaya_files';

    protected $casts = [
        'metadata' => 'array',
    ];
}

When both default models are replaced, publish and own the migrations in your application. Sanchaya only auto-loads package migrations for the default file or attachment models.

Override Action Classes

Each configured action is resolved from Laravel's container. Create a class with the same public method contract as the action you are replacing; extending the shipped class is the safest starting point.

// config/filament-sanchaya.php
'actions' => [
    'delete' => [
        'enabled' => true,
        'label' => 'Delete',
        'icon' => 'heroicon-m-trash',
        'class' => \App\Actions\MyCustomDeleteAction::class,
    ],
],

namespace App\Actions;

use DP0\Sanchaya\Actions\DeleteAction;
use DP0\Sanchaya\Models\SanchayaFile;

class MyCustomDeleteAction extends DeleteAction
{
    public function execute(SanchayaFile $item): bool
    {
        // Add audit logging, external cleanup, or business checks here.

        return parent::execute($item);
    }
}

The preview action has configurable visibility, label, and icon, but it does not resolve a backend action class.

Automated Testing

Sanchaya includes an automated test suite covering actions, models, traits, form/table/infolist components, and Livewire browser interactions. Run these commands from a Laravel application that includes the package source and its test namespace; they are for package development, not consumer installation.

# Run all tests via PHPUnit or Artisan
php artisan test packages/dp0/filament-sanchaya/tests

# Run specific suite
php artisan test --filter=CreateFolderActionTest

Troubleshooting