---

This package allows you to create fzf powered menus straight from your PHP code.

Features

• Automatic fzf binary download
• Inline fzf configuration

Installation

Install the package:

composer require mantas6/fzf-php

Usage

Options

Options can be provided in a multitude of ways.

Strings

<?php
use function Mantas6\FzfPhp\fzf;

$selected = fzf(['Apple', 'Orange', 'Grapefruit']);

// 'Apple'

• Returns null if user cancels (^C) the prompt

Arrays

<?php

$selected = fzf(
    options: [
        ['Apples', '1kg'],
        ['Oranges', '2kg'],
        ['Grapefruits', '3kg'],
    ]
);

// ['Apples', '1kg']

• Each array element represents different column in the finder

Objects

Using toArray

<?php

$selected = fzf(
    options: [
        new Model('Apple'),
        new Model('Orange'),
        new Model('Grapefruits'),
    ]
);

// new Model('Apple')

• The object class must implement toArray

Implementing PresentsForFinder interface

If using toArray method is not feasible, an interface can be implemented instead.

<?php

use Mantas6\FzfPhp\Concerns\PresentsForFinder;

class Model implements PresentsForFinder
{
    protected string $name;

    public function presentForFinder(): array
    {
        return [$this->name];
    }
}

Providing a presenter

To untie the presentation from the model, more reusable approach can be used.

<?php

$selected = fzf(
    options: [
        new Model('Apple'),
        new Model('Orange'),
        new Model('Grapefruits'),
    ],

    present: fn (Model $item): array => [$item->name],
);

// or

$selected = fzf(
    // ...
    present: new ModelPresenterInvokable,
);

• The callable must always return an array

Options as object

Instead of passing options as array, object can be used.

<?php

$selected = fzf(
    options: new MyCustomCollection,
);

The class needs to meet one of the following requirements:

• Must implement the native Traversable interface
• Needs to implement toArray() method

Options styling

Option columns can be styling using cell() helper function in the presenter callback.

<?php

use function Mantas6\FzfPhp\cell;

$selected = fzf(
    options: [
        ['name' => 'Apples', 'weight' => 1000],
        ['name' => 'Oranges', 'weight' => 2000],
        ['name' => 'Grapefruits', 'weight' => 3000],
    ],

    // Styling individual items
    present: fn (array $item): array => [
        $item['name'],

        cell($item['weight'], fg: $item['weight'] > 2000 ? 'red' : 'green'),
    ],
);

Formatting options are:

• string value - text of the cell
• string align - alignment in the table (left, right, center)
• string fg - foreground color
• string bg - background color
• int colspan - column span

Multi mode

Retrieve multiple options from a list.

<?php

$selected = fzf(
    options: ['Apple', 'Orange', 'Grapefruit'],
    arguments: ['multi' => true],
);

// ['Apple', 'Orange']

• Returns [] if user cancels (^C) the prompt

Arguments

Pass any other fzf configuration arguments:

<?php

$selected = fzf(
    options: ['Apple', 'Orange', 'Grapefruit'],
    arguments: [
        'height' => '40%',
        'ansi' => true,
        'cycle' => true,
    ],
);

• Arguments delimiter (or d), with-nth are used internally, and will be overridden if specified
• Arguments that transform output may not be supported
• Preview and reload are not currently supported

Reusable object approach

If options are not provided, the object is returned.

<?php

$finder = fzf();

$fruit = $finder->ask(['Apple', 'Orange', 'Grapefruit']);

// ...

$weight = $finder->ask(['250g', '500g', '1kg']);

Configuration can be passed to pre-configure the instance.

<?php

$finder = fzf(arguments: ['height' => '50%']);

$finder->ask(['apple', 'orange', 'grapefruit']);

Additional configuration is available through the class methods.

<?php

$finder->present(...);

$finder->arguments(...);

Configuration

Use system fzf binary instead of fetching it.

<?php
// YourAppServiceProvider.php

use Mantas6\FzfPhp\FuzzyFinder;

FuzzyFinder::usingCommand(['/usr/bin/env', 'fzf']);

• Automatic binary download will be disabled when custom command is set

Set global arguments for all prompts.

<?php
// YourAppServiceProvider.php

FuzzyFinder::usingDefaultArguments(['pointer' => '->']);

Binary download

The fzf binary is downloaded automatically on the first use, however you can initiate the download manually.

./vendor/bin/fzf-php-install

See also:

• fzf GitHub page