CDS-io-console
This documents describes a set of interfaces that try to abstract the CLI interface of PHP in a compatible manner.
Many parts are based on existing implementation of console features and try to cover them.
This document directly builds up on CDS-io, so you might read that one first.
Why?
In a world with Composer, many PHP projects have a huge code-base. This allows for functional applications, but there are many cases in which you're require to use the console for intensive tasks, e.g. importing- and exporting content, generating and scaffolding as well as managing your overall web-application.
Because of that, the IO-parts of current PHP applications are currently split by the SAPI: You either are in CLI mode or you're in HTTP-mode.
The following interfaces try to combine the best parts of both worlds, providing a single interface to access all parts of it.
The ConsoleInput Interface
The common task of classes implementing the ConsoleInput interface is providing access to the actual command that has been called as well as its arguments.
It should be a wrapper over STDIN, so the ReadableInterface-methods should all work with and on STDIN.
<?php
namespace Cds\Io\Console;
use Cds\Io\Stream\ReadableInterface;
interface ConsoleInput implements ReadableInterface
{
/**
* Returns the path of the currently invoked command.
*
* e.g. with "php bin/console some:command", this will return "php bin/console"
*
* @return string
*/
public function getCommandPath();
/**
* Returns an array of passed arguments.
*
* These describe unnamed arguments.
* e.g. with "php bin/console some:command some-argument --help" this will return ['some:command', 'some-argument']
*
* If no arguments are given, this will return an empty array
*
* @return array the array of unnamed options
*/
public function getArguments();
/**
* Returns a specific argument based on it's numerical index.
*
* If the argument at the given index doesn't exist, the passed default value will be returned
*
* @param int the index of the argument to read
* @param mixed the default value to return, if the argument is not set (default: null)
*
* @return string the value of the given argument
*/
public function getArgument($index, $defaultValue = null);
/**
* Gets an array of all named options.
*
* These describe named options passed to the command (-a, -h, --help etc.)
* Notice that the short-names of options MUST NOT appear in the returned array.
*
* With "php bin/console some:command -hx --path-name some/path", the output will be
* ['help' => true, 'extended' => true, 'path-name' => 'some/path'] where -h maps to help and -x maps to extended
*
* Boolean switches should be automatically set to true/false respectively (implementor's task)
*
* @return array the array of named options
*/
public function getOptions();
/**
* Returns a specific option based on it's long name.
*
* If the option with the given name doesn't exist, the passed default value will be returned
*
* @param string the name of the option to read
* @param mixed the default value to return, if the option is not set (default: null)
*
* @return string|bool the value of the given option
*/
public function getOption($name, $defaultValue = null);
}This wraps all basic information needed from input over the console. Notice that we didn't include things like isInteractive on purpose, as this is very implementor-specific. Smaller console-libraries might not need interaction in any way.
The ConsoleOutput Interface
The Output-interface is basically just a wrapper over STDOUT. It's main reason for it to even exist is consistency and as a way to provide simpler output mechanisms when working on the console only.
<?php
namespace Cds\Io\Console;
use Cds\Io\Stream\WritableInterface;
interface ConsoleOutput implements WritableInterface
{
/**
* Returns whether the current CLI implementation supports ANSI escape sequences.
*
* @return bool
*/
public function supportsDecoration();
}To disable and enable ANSI-escaping is a task of the implementor, some implementations may just automatically default it in any case. It's still important that we can get the information if the underlying CLI implementation supports it. How this information is retrieved is, again, task of the implementor.
If you were searching for writeLine and writeFormat, these are not implemented in this really basic interface as it is primarily just about containing data, not formatting it. These two might be implemented in some kind of WriterInterface implements WritableInterface later on, which then can contain ConsoleOutput and can be passed as an OutputInterface just as well.
Example Implementations
None currently. I'm sorry.
CDS-io-console
This documents describes a set of interfaces that try to abstract the CLI interface of PHP in a compatible manner.
Many parts are based on existing implementation of console features and try to cover them.
This document directly builds up on CDS-io, so you might read that one first.
Why?
In a world with Composer, many PHP projects have a huge code-base. This allows for functional applications, but there are many cases in which you're require to use the console for intensive tasks, e.g. importing- and exporting content, generating and scaffolding as well as managing your overall web-application.
Because of that, the IO-parts of current PHP applications are currently split by the SAPI: You either are in CLI mode or you're in HTTP-mode.
The following interfaces try to combine the best parts of both worlds, providing a single interface to access all parts of it.
The
ConsoleInputInterfaceThe common task of classes implementing the
ConsoleInputinterface is providing access to the actual command that has been called as well as its arguments.It should be a wrapper over STDIN, so the
ReadableInterface-methods should all work with and on STDIN.This wraps all basic information needed from input over the console. Notice that we didn't include things like
isInteractiveon purpose, as this is very implementor-specific. Smaller console-libraries might not need interaction in any way.The
ConsoleOutputInterfaceThe Output-interface is basically just a wrapper over STDOUT. It's main reason for it to even exist is consistency and as a way to provide simpler output mechanisms when working on the console only.
To disable and enable ANSI-escaping is a task of the implementor, some implementations may just automatically default it in any case. It's still important that we can get the information if the underlying CLI implementation supports it. How this information is retrieved is, again, task of the implementor.
If you were searching for
writeLineandwriteFormat, these are not implemented in this really basic interface as it is primarily just about containing data, not formatting it. These two might be implemented in some kind ofWriterInterface implements WritableInterfacelater on, which then can contain ConsoleOutput and can be passed as anOutputInterfacejust as well.Example Implementations
None currently. I'm sorry.