README

Flysystem Filter is a lightweight and intuitive filtering layer for League/Flysystem. It provides an easy-to-use FilterBuilder for logical and chainable filtering of filesystem contents (DirectoryListing).

Features

Simple Filtering: Filter filesystem contents without writing complex callback functions.
Logical Expressions: Combine conditions using and(), or(), group_start(), and group_end().
Chainable API: Build complex filters with a readable, chainable syntax.
Integration with Flysystem: Works seamlessly with League/Flysystem's DirectoryListing.

Installation

Install via Composer:

composer require marktaborosi/flysystem-filter

Usage

Simple Example

Here's a basic example that filters only files:

use League\Flysystem\Filesystem;
use League\Flysystem\Local\LocalFilesystemAdapter;
use Marktaborosi\FlysystemFilter\FilterBuilder;
use Marktaborosi\FlysystemFilter\FlysystemFilter;

require 'vendor/autoload.php';

$adapter = new LocalFilesystemAdapter(__DIR__ . '/tests/Storage/');
$flysystem = new Filesystem($adapter);
$flysystemContents = $flysystem->listContents('', true);

$filter = new FilterBuilder();
$filter->isFile();

$filteredResults = FlysystemFilter::filter($flysystemContents, $filter);

foreach ($filteredResults as $result) {
    echo $result->path() . PHP_EOL;
}

Advanced Example

Filter files with advanced conditions:

$filter = new FilterBuilder();
$filter
    ->extensionEquals(['txt', 'log'])
    ->and()
    ->isPublic()
    ->and()
    ->sizeLt('1G');

$filteredResults = FlysystemFilter::filter($flysystemContents, $filter);

Using Grouping and Logical Operators

You can group conditions to create complex expressions:

$filter = new FilterBuilder();
$filter
    ->group_start()
        ->extensionContains(['log', 'txt'])
        ->and()
        ->isFile()
    ->group_end()
    ->or()
    ->pathMatchesRegex('/debug/');

$filteredResults = FlysystemFilter::filter($flysystemContents, $filter);

API Overview

Filtering Options

General Conditions

isFile(): Matches file entries.
isDirectory(): Matches directory entries.

Path-Based Conditions

pathEquals($paths): Matches exact paths. Accepts string or array.
pathContains($substrings): Matches paths containing specific substrings. Accepts string or array.
pathMatchesRegex($pattern): Matches paths using a regex pattern.

Filename-Based Conditions

filenameEquals($filenames): Matches filenames without extensions. Accepts string or array.
filenameContains($substrings): Matches filenames containing specific substrings. Accepts string or array.
filenameMatchesRegex($pattern): Matches filenames using a regex pattern.

Size-Based Conditions

sizeEquals($size): Matches files of a specific size.
sizeGt($size): Matches files larger than a specific size.
sizeLt($size): Matches files smaller than a specific size.
Note: Sizes can be specified in units like B, K, M, G, T.

Date-Based Conditions

lastModifiedBefore($timestamp): Matches files modified before a specific timestamp.
lastModifiedAfter($timestamp): Matches files modified after a specific timestamp.

Logical Operators

and(): Combines conditions with logical AND.
or(): Combines conditions with logical OR.
group_start() / group_end(): Groups conditions to control logical precedence.

Requirements

PHP 8.2 or higher
League/Flysystem 3.29 or higher

Development

Run the tests:

composer test

Contributing

Feel free to contribute to the project by submitting issues or pull requests on GitHub.

License

This project is licensed under the MIT License. See the LICENSE file for details.

marktaborosi / flysystem-filter

Maintainers

Details