CLI and the Console¶
In writing an application tailored for the CLI, you can leverage the popphp/pop-console component to help you configure and build your application for the console. Please note, While there is support for CLI-based applications to run on both Windows and Linux/Unix based systems, the popphp/pop-console component’s colorize feature is not supported in Windows CLI-based applications.
Before getting into utilizing the popphp/pop-console component with CLI-based applications, let’s take a look at some simple CLI scripts to call and execute your PHP scripts. For these examples, let’s assume you have a small PHP script like this:
<?php echo 'Hello ' . $argv;
If we would like to access and run that script via a simple command, there a few ways to do it.
Natively on Linux/Unix
Add #!/usr/bin/php as the first line to the PHP script above (or wherever your PHP binary is located):
#!/usr/bin/php <?php echo 'Hello, ' . $argv;
You can then name the script without a PHP extension, for example foo, make it executable and run it.
$ ./foo pop
If you want to use a BASH script as a wrapper to access and run your PHP script, named foo.php in this case, then you can create a BASH script file like this:
#!/bin/bash php ./foo.php $@
Let’s name the BASH script app and make it executable. Then you can run it like this:
$ ./app pop
Similarly on Windows, you can create a batch file to do the same. Let’s create a batch file called app.bat:
@echo off php foo.php %*
Then on the Windows command line, you can run:
C:\> app pop
In the above examples, the initial example PHP script is accessing an argument from the $argv array, which is common. As you can see, all the examples pushed the argument value of ‘pop’ into the script, as to echo Hello, pop on the screen. While PHP can access that value via the $argv array, BASH scripts and batch files can pass them into the PHP scripts via:
#!/bin/bash php ./foo.php $1 $2 $3
@echo off php foo.php %1 %2 %3
Of course, those examples only allow for up to 3 arguments to be passed. So, as you can see, the examples above for BASH and batch files use the catch-alls $@ and %* respectively, to allow all possible parameters to be passed into the PHP script.
#!/bin/bash php ./foo.php $@
@echo off php foo.php %*
Using the popphp/pop-console component when building a CLI-based application with Pop gives you access to a set of features that facilitate the routing and display of your application.
Here’s a look at the basic API:
$console->setWidth(80);- sets the character width of the console
$console->setIndent(4);- sets the indentation in spaces at the start of a line
$console->setHeader($header);- sets a header to prepend to the output
$console->setFooter($footer);- sets a footer to append to the output
$console->colorize($string, $fg, $bg);- colorize the string and return the value
$console->setHelpColors($color1, $color2, $color3);- set colors to use for the help screen
$console->addCommand($command);- add a command to the console object
$console->addCommands($commands);- add an array of commands to the console object
$console->addCommandsFromRoutes($routeMatch, $scriptName = null);- add commands based on routes config
$console->prompt($prompt, $options, $caseSensitive, $length, $withHeaders);- call a prompt and return the answer
$console->append($text = null, $newline = true);- appends text to the current console response body
$console->write($text = null, $newline = true, $withHeaders = true);- appends text to the current console response body and sends the response
$console->send();- sends the response
$console->help();- sends the auto-generated help screen
$console->clear();- clears the console screen (Linux/Unix only)
You can use a console object to manage and deploy output to the console, including a prepended header and appended footer.
$console = new Pop\Console\Console(); $console->setHeader('My Application'); $console->setFooter('The End'); $console->append('Here is some console information.'); $console->append('Hope you enjoyed it!'); $console->send();
The above will output:
My Application Here is some console information. Hope you enjoyed it! The End
On consoles that support it, you can colorize text outputted to the console with the
$console->append( 'Here is some ' . $console->colorize('IMPORTANT', Console::BOLD_RED) . ' console information.' );
The list of available color constants are:
Using a Prompt¶
You can also trigger a prompt to get information from the user. You can enforce a certain set of options as well as whether or not they are case-sensitive:
$console = new Pop\Console\Console(); $letter = $console->prompt( 'Which is your favorite letter: A, B, C, or D? ', ['A', 'B', 'C', 'D'], true ); echo 'Your favorite letter is ' . $letter . '.';
./pop Which is your favorite letter: A, B, C, or D? B // <- User types 'B' Your favorite letter is B.
You can register commands with the console object to assist in auto-generating a well-formatted, colorized help screen.
use Pop\Console\Console; use Pop\Console\Command; $edit = new Command( 'user edit', '<id>', 'This is the help for the user edit command' ); $remove = new Command( 'user remove', '<id>', 'This is the help for the user remove command' ); $console = new Console(); $console->addCommand($edit); $console->addCommand($remove); $console->setHelpColors( Console::BOLD_CYAN, Console::BOLD_GREEN, Console::BOLD_YELLOW );
Once the commands are registered with the main $console object, we can generate the help screen like this:
The above command will output an auto-generated, colorized help screen with the commands that are registered with the console object.