Getting Started

Start by installing the package via Composer:

composer require phpdocumentor/flyfinder

The primary entry point is the Flyfinder class. Its simplest use case is offering a keyboard-navigable fuzzy picker over an array of strings—like file paths or command names:

use phpDocumentor\FlyFinder\Flyfinder;

$items = ['config/app.php', 'src/Kernel.php', 'routes/web.php', 'tests/Feature/ExampleTest.php'];

$finder = new Flyfinder($items);
$selected = $finder->run();

echo "You selected: {$selected}\n";

Key first steps:

Read the README for basic usage.
Check the examples/ directory in the repo for concrete, minimal scripts.
Try the example with php examples/files.php to see fuzzy file selection in action.

Implementation Patterns

1. Fuzzy File Selector (CLI Tooling)

Use Flyfinder to let users pick files interactively in config generators, scaffolding tools, or migration helpers:

use phpDocumentor\FlyFinder\Flyfinder;
use phpDocumentor\FlyFinder\Source\FileSystemSource;

$source = new FileSystemSource(__DIR__ . '/src', ['php', 'yaml'], recursive: true);
$finder = new Flyfinder($source);
$selected = $finder->run();

2. Command Selection (Dynamic CLI)

Build a self-documenting CLI tool that lets users choose from available commands:

$commands = ['make:migration', 'db:seed', 'queue:work', 'optimize:clear'];
$finder = new Flyfinder($commands);
$cmd = $finder->run();

3. Custom Data Sources

Implement phpDocumentor\FlyFinder\Source\SourceInterface to support dynamic or remote data (e.g., API endpoints, Git refs):

class GitBranchesSource implements SourceInterface {
    public function all(): array {
        return array_filter(explode("\n", trim(shell_exec('git branch --format="%(refname:short)"'))));
    }
}
$finder = new Flyfinder(new GitBranchesSource());

4. Integration with Symfony Console

Use within a Command::execute() to offer interactive selection:

protected function execute(InputInterface $input, OutputInterface $output): int {
    $output->write('Select environment: ');
    $envs = ['local', 'staging', 'prod'];
    $choice = (new Flyfinder($envs))->run();
    $output->writeln("Selected: {$choice}");
    // … proceed with action
}

Tips for Performance

Use FileSystemSource for large directory trees—it optimizes path scanning and excludes large files by default.
For large in-memory lists (>10k), preload or lazy-load via custom sources.
Set $finder->setCaseSensitive(false) for user-friendliness.

Gotchas and Tips

PHP Version: Requires ≥8.1; uses typed properties and match expressions—don’t try to backport to 7.x.
TTY Dependency: Flyfinder only works in a TTY-enabled terminal (php script.php won’t behave in pipes or cron). Use posix_isatty(STDIN) to guard before calling run().
Encoding Issues: On Windows, ensure your console uses UTF-8 (e.g., chcp 65001). Non-printable characters may break the UI—sanitize inputs.
Custom Styling: Colors and cursor movement rely on ANSI escape codes. Avoid running under strict error_reporting(E_ALL)—Flyfinder uses set_exception_handler() internally for graceful handling.
Extensibility: Extend Flyfinder to override filter() (e.g., custom scoring) or render() for themed UI (e.g., dark/light mode).
Testing: Mock SourceInterface or wrap Flyfinder in a service so tests can inject a static array—don’t rely on interactive prompts in CI.
Fallback Behavior: If user presses Esc, Flyfinder returns null. Always handle this explicitly to avoid silent failures.
Performance Note: Fuzzy search uses prefix + substring + camelCase heuristics—slow on very long strings (>200 chars). Truncate or normalize in your source if needed.

Flyfinder Laravel Package