Edit this page on Github

Spress >= 1.1

The IO API enables your plugins to interact with the user to show messages or to make questions:

  • Write messages.
  • Ask.
  • Ask confirmation (for yes/no questions).
  • Ask and hide answer (useful for get password answer).
  • Ask for a choice.

IO API implements IOInterface defined at Spress Core.

How to use?

The first step is to get a IO API instance using spress.start event and getIO method. This method returns a Yosymfony\Spress\IO\ConsoleIO instance.

class SpressIOExample extends Plugin
{
    private $io;

    public function initialize(EventSubscriber $subscriber)
    {
        $subscriber->addEventListener('spress.start', 'onStart');
    }

    public function onStart($event)
    {
        $this->io = $event->getIO();

        if($this->io->isInteractive())
        {
            $this->io->write('Welcome to Github plugin for Spress.', true);
            $answer = $this->io->askConfirmation(
                "Do you want to connect to your Github account? ",
                false);

            if($answer)
            {
                $this->io->ask('username: ');
                $this->io->askAndHideAnswer('password:');
            }
        }
    }
}

Before make a question to user is recommendable to know if the interface is interactive using isInteractive method.

IO API methods

  • write: Write a message: $io->write('message', true). The second argument let you set a new line. Spress >= 2.2 There is a third optional argument for setting the verbosity level. VERBOSITY_NORMAL by default. e.g: $io->write('message', true, IOInterface::VERBOSITY_NORMAL).

  • overwrite: Spress >= 2.2 Overwrites a previous message to the output: $io->overwrite('message'). This method has the same sign that write method.

  • ask: Ask a question: $io->ask('question?', null). The second argument is the default answer if the user enters nothing.
  • askConfirmation: yes/no question. $io->askConfirmation('do you want?', true). The second argument is the default answer if the user enters nothing.
  • askAndValidate: Ask a question with a callback function to validate the response.
  • askAndHideAnswer: Ask a question and hide the answer. This method is useful to require password.
  • askHiddenResponseAndValidate: This method is like before but using a callback function to validate the response.
  • askChoice: Spress >= 2.2 Asks the user to select a value: $io->askChoice('Select a color', ['blue', 'green'], 'green'). The first argument corresponds to the question. Second argument is for available options and the last one indicates the default value.
  • isInteractive: Is this input means interactive?: $io->isInteractive().
  • isVerbose: Is this output verbose? $io->isVerbose().
  • isDebug: Is the output in debug verbosity?: $io->isDebug().

If you are using a callback function for validating an answer the validator receives the data to validate. It must return the validated data when the data is valid and throw an exception otherwise.

Verbosity levels

In the CLI tool, the verbosity level could be change using the options -vv, -vvv.

Verbosity levels available:

  • IOInterface::VERBOSITY_QUIET
  • IOInterface::VERBOSITY_NORMAL
  • IOInterface::VERBOSITY_VERBOSE
  • IOInterface::VERBOSITY_VERY_VERBOSE
  • IOInterface::VERBOSITY_DEBUG