BASH/ZSH auto-complete for Symfony Console applications

This package provides automatic (tab) completion in BASH and ZSH for Symfony Console Component based applications. With zero configuration, this package allows completion of available command names and the options they provide. Custom completion behaviour can be added for option and argument values by name.

Example of zero-config use with Composer:

Zero-config use

If you don't need any custom completion behaviour, all you need to do is add the completion command to your application's available commands:

Install stecman/symfony-console-completion through composer
Add an instance of CompletionCommand to your application's Application::getDefaultCommands() method:

protected function getDefaultCommands()
{
   //...
    $commands[] = new \Stecman\Component\Symfony\Console\BashCompletion\CompletionCommand();
   //...
}

Register completion for your application by running one of the following in a terminal, replacing [program] with the command you use to run your application (eg. 'composer'):

# BASH 4.x, ZSH
source <([program] _completion --generate-hook)

# BASH 3.x, ZSH
[program] _completion --generate-hook | source /dev/stdin

# BASH (any version)
eval $([program] _completion --generate-hook)

By default this registers completion for the absolute path to you application. You can specify a command name to complete for instead using the -p option, which is useful if you're using an alias to run the program.

Add the command from step 3 to your bash profile if you want the completion to apply automatically for all new terminal sessions.

Note: If [program] is an alias you will need to specify the aliased name with the -p|--program option, as completion may not work otherwise: _completion --generate-hook -p [myalias].

Second note: The type of shell (ZSH/BASH) is automatically detected using the SHELL environment variable at run time. In some circumstances, you may need to explicitly specify the shell type with the --shell-type option.

How it works

The --generate-hook option of CompletionCommand generates a few lines of BASH that, when executed, register your application as a completion handler for your itself in the current shell session. When you request completion for your program (by pressing tab), the completion command on your application is run with no arguments: [program] _completion. This uses environment variables set by BASH to get the current command line contents and cursor position, then completes from your console command definitions.

Custom completion

Custom completion behaviour for argument and option values can be added by sub-classing CompletionCommand.

The following examples are for an application with this signature: myapp (walk|run) [-w|--weather=""] direction

class MyCompletionCommand extends CompletionCommand {

    protected function runCompletion()
    {
        $this->handler->addHandlers(array(
            // Instances of Completion go here.
            // See below for examples.
        ));
        return $this->handler->runCompletion();
    }
}

Command-specific argument completion with an array

$this->handler->addHandler(
    new Completion(
        'walk',
        'direction',
        Completion::TYPE_ARGUMENT,
        array(
            'north',
            'east',
            'south',
            'west'
        )
    )
);

This will complete for this:

$ myapp walk [tab]

but not this:

$ myapp run [tab]

Non-command-specific (global) argument completion with a function

$this->handler->addHandler(
    Completion::makeGlobalHandler(
        'direction',
        Completion::TYPE_ARGUMENT,
        function() {
            $values = array();

            // Fill the array up with stuff
            return $values;
        }
    )
);

This will complete for both commands:

$ myapp walk [tab]
$ myapp run [tab]

Option completion

Option handlers work the same way as argument handlers, except you use Completion::TYPE_OPTION for the type..

$this->handler->addHandler(
    Completion::makeGlobalHandler(
        'weather',
        Completion::TYPE_OPTION,
        array(
            'raining',
            'sunny',
            'everything is on fire!'
        )
    )
);

Example: completing references from a Git repository

Completion::makeGlobalHandler(
    'ref',
    Completion::TYPE_OPTION,
    function () {
        $raw = shell_exec('git show-ref --abbr');
        if (preg_match_all('/refs\/(?:heads|tags)?\/?(.*)/', $raw, $matches)) {
            return $matches[1];
        }
    }
)

Example: completing filesystem paths

This library provides the completion class ShellPathCompletion which defers path completion to the shell's built-in path completion behaviour rather than implementing it in PHP.

new Completion\ShellPathCompletion(
    Completion::ALL_COMMANDS,
    'path',
    Completion::TYPE_OPTION
)

Behaviour notes

Option shortcuts are not offered as completion options, however requesting completion (ie. pressing tab) on a valid option shortcut will complete.
Completion is not implemented for the --option="value" style of passing a value to an option, however --option value and --option "value" work and are functionally identical.

aik099/symfony-console-completion