Filters

You use filters to remove items from the pipeline. Filters implement FilterInterface and must provide a filter() method. Every item of the pipeline is passed to the filter and if the return value evaluates to false (false, null, 0, ...) the item is no further processed.

Plum comes with some default filters, but you can also create your own custom filters.

Table of Contents

• CallbackFilter
• FileExtensionFilter
• Custom Filters

CallbackFilter

The CallbackFilter calls a function and checks the return value of that function.

use Cocur\Plum\Filter\CallbackFilter;

$filter = new CallbackFilter(function ($item) {
    return preg_match('/https?:\/\/[a-z0-9-]+\.[a-z]+/', $item);
});
$filter->filter('https://florian.ec'); // -> true

FileExtensionFilter

Checks if the file extension of a file name matches.

use Cocur\Plum\Filter\FileExtensionFilter;

$filter = new FileExtensionFilter('md');
$filter->filter('README.md'); // -> true
$filter->filter('README.html'); // -> false

If the item is are more complex structure, for example, an array or an object FileExtensionFilter uses Symfony's PropertyAccess to retrieve the filename from the item. You can pass the path to the property as the second argument to the constructor.

use Cocur\Plum\Filter\FileExtensionFilter;

$filterArray = new FileExtensionFilter('md', '[filename]');
$filterArray->filter(['filename' => 'README.md']); // -> true
$filterArray->filter(['filename' => 'README.html']); // -> false

$item = new stdClass();
$item->filename = 'README.md';
$filterObject = new FileExtensionFilter('md', 'filename');
$filterObject->filter($item); // -> true
$item->filename = 'README.html';
$filterObject->filter($item); // -> false

The extension passed to the constructor can also be an array. The filter returns true if the given item matches any of the extensions in the array.

$filter = new FileExtensionFilter(['md', 'html']);
$filter->filter('file.md'); // -> true

Custom Filters

You can create a custom filter by creating a class that implements Cocur\Plum\Filter\FilterInterface. The interface requires you to implement a filter() method that expects a single argument and returns either true or false. Plum processes items of all types, simple scalar types (such as strings or integers) as well as complex types (arrays or objects) and therefore Plum does not guarantee the type of the item passed to filter().

use Cocur\Plum\Filter\FilterInterface;

class RegExpFilter implements FilterInterface
{
    private $pattern;

    public function __construct($pattern)
    {
        $this->pattern = $pattern;
    }

    public function filter($item)
    {
        return 1 === preg_match($this->pattern, $item);
    }
}