Modifications

A modification is a concept to describe the process of "transmitting" information about a certain "modification" to the target used to retrieve media. A modification could be scoping or ordering a query. As each driver has a different way of retrieving media, filters and sorters cannot just provide one implementation to modify this target. Therefore, each filter or sorter (when applied) translates to a set of one or more modifications. Then, these are passed to the driver when retrieving items. The driver is responsible for handling each modification and applying that to the target.

Thus, in short, a modification is responsible for "holding" the information about how to scope or order the results, and the driver is responsible for "applying" that modification to the target.

The target can be anything, depending on the driver. It can be an Eloquent query, a Symfony Finder instance, or something else.

Modifications are an internal concept, and are only used when creating custom filters or sorters. If you are just using the built-in filters and sorters, you don't need to worry about modifications.

Generally, there are two type of modifications:

• Scopes: these modifications limit the results to a subset of items.
• Orders: these modifications change the order of the results, but do not modify them.

For instructions on creating a custom filter or custom sorter, see the respective documentation.

Creating modifications

Scope modification

Creating a modification is as simple as creating a class that extends the RalphJSmit\Filament\Explore\Drivers\Modifications\Modification. I would recommend to organize your modifications in a separate Scopes and Orders directory:

use RalphJSmit\Filament\Explore\Drivers\Modifications\Modification;

class PublishedModification extends Modification
{
    protected bool $isPublished;
    
    public function published(bool $condition = true): static
    {
        $this->isPublished = $condition;

        return $this;
    }
    
    public function isPublished(): bool
    {
        return $this->isPublished;
    }
}

Then, your filter would use them as follows:

use App\MediaLibrary\Modifications\Scopes\PublishedModification;
use RalphJSmit\Filament\Explore\Filters\Filter;

class PublishedFilter extends Filter
{
    // ...

    public function getModifications(array $data): array
    {
        $modifications = [];

        if (filled($isPublished = $data['is_published'] ?? null)) {
            $modifications[] = PublishedModification::make()
                ->published($isPublished);
        }

        return $modifications;
    }
}

Order modification

Creating an order modification is similar to creating a scope modification. The difference is that generally, order modifications will only have a ->sortDirection() method and no additional configuration:

use RalphJSmit\Filament\Explore\Drivers\Modifications\Modification;
use RalphJSmit\Filament\Explore\Sorters\Enums\SortDirection;

class PublishedModification extends Modification
{
    protected SortDirection $sortDirection;

    public function sortDirection(SortDirection $sortDirection): static
    {
        $this->sortDirection = $sortDirection;

        return $this;
    }

    public function getSortDirection(): SortDirection
    {
        return $this->sortDirection;
    }
}

Sorters are activated by one click. Therefore, there are generally no further public exposed configuration methods. However, you are free to add public methods if needed.

Registering modifications

Next, as each driver has a different way of retrieving media, we need to register the modification in the driver, and provide an actual "implementation" of how to apply the modification. This can be done in two ways. If you have not set a custom driver, I would recommend to use the first way. If you have created a custom driver, you can use either way.

Within panel-provider

In your panel-provider, you can register a modification-closure for a specific driver. This closure receives the modification and the target object.

$plugin
    ->driver(MediaLibraryItemDriver::class, function (MediaLibraryItemDriver $driver) {
        $driver->applyModificationUsing(function (mixed $target, Modification $modification, Closure $next) {
            if ($modification instanceof PublishedModification) {
                return $target->where('is_published', $modification->isPublished());
            }
            
            return $next($target, $modification);
        });
    });

Within driver

Each driver has to implement a method called applyModification(). This method receives the modification and the target object. If you have created a custom driver or are extending a driver, I would recommend this way.

In the applyModification() method, you can then check the type of modification, and apply it to the queryable object:

class CustomDriver extends Driver
{
    /**
     * @param YourTargetObject $target 
     */
    public function applyModification(mixed $target, Modification $modification): mixed
    {
        if ($modification instanceof PublishedModification) {
            return $target->where('is_published', $modification->isPublished());
        }
        
        // Other modifications, in a custom driver make sure to handle every available modification...

        return parent::applyModification($modification, $target);
    }
    
    // ...
}

Using one of the above ways, your modification can now always be applied by the driver when retrieving media.