In this post we're covering how to create a simple CLI app with the help of MiniCLI. What we'll be creating is a small CLI tool to ping websites.
Setting up our requirements.
The first thing we do is to create a folder for our new tool, which I'll name ping-cli
and require the minicli/minicli
package.
composer require minicli/minicli
Let's also create a .gitignore
to make sure the /vendor
folder doesn't get added to source control.
vendor/
composer.lock
Creating our entry-point.
With the requirements done we can continue on to creating our entry-point. This is what'll be called from the command-line. Create a bin
folder and a file named ping-cli
.
mkdir bin && touch bin/ping-cli
Now we can use bash
and the minicli
package to create our new tool. Start by using a shebang to load our new ping-cli
file in a php
environment, and add out opening php
tags.
#!/usr/bin/env php
<?php declare(strict_types = 1);
You can omit declare
if you don't want strict typing.
Before moving on to using minicli
, we must first make sure we're calling this file from the CLI. We do this with the php_sapi_name
functions, which returns the string of our current interface.
if (php_sapi_name() !== 'cli') {
exit;
}
Integrating with MiniCLI.
To integrate minicli
we include the composer
autoloader and instantiate a new Minicli
class.
We do this by establishing a new variable $root
to hold the parent directory of the directory bin/ping-cli
. Adding a check to see if we can grab the autoloader using that path. Should that operation be false, we will set the $root
to be 4
levels up from our parent directory.
This is done so that if our tool is required and is symlinked to vendor/bin/ping-cli
, we use the autoloader generated by the outside project correctly.
Lastly we require the autoloader and instantiate a new Minicli\App
.
$root = dirname(__DIR__);
if (! is_file($root . '/vendor/autoload.php')) {
$root = dirname(__DIR__, 4);
}
require $root . '/vendor/autoload.php';
use Minicli\App;
$app = new App();
To get the CLI tool to run, we have to call the runCommand
method on our $app
. Add the following line to the end of our ping-cli
file.
$app->runCommand($argv);
The $argv
variable is a reserved variable provided to us by PHP, you can read more about it in the documentation.
Running our command now will output ./minicli help
to the console, try it yourself by running the command.
./bin/ping-cli
Updating our CLI signature.
Before embarking on the journey of creating the new command, let us first update our signature. This signature will replace the default ./minicli help
signature ran when running our tool with no input.
We set our new signature using the setSignature
method on the minicli
$app
.
$app->setSignature(<<<EOD
_ ___
____ (_)___ ____ _ _____/ (_)
/ __ \/ / __ \/ __ `/_____/ ___/ / /
/ /_/ / / / / / /_/ /_____/ /__/ / /
/ .___/_/_/ /_/\__, / \___/_/_/
/_/ /____/ \e[0;32m Ver. 0.0.1
EOD);
This will give us the following signature.
Registering our command.
With the basic setup out-the-way, let's continue on by registering our ping
command. Since this tool will only have a single command, we will forgo registering a namespace and just register a single command with the registerCommand
method.
To register the command, we pass it the name
and the callable
which will get passed the $input
. For convenience we will also use the $app
in out callable
.
use Minicli\Command\CommandCall;
$app->registerCommand('ping', function (CommandCall $input) use ($app) {
$app->getPrinter()->success('We have lift-off! π');
});
Calling the getPrinter
method access the output handler, which we then use to print a success
message to the console.
Running ./bin/ping-cli ping
will now print back We have lift-off! π in our console.
Updating our command.
With the command registered, let us move swiftly along to implementing our real ping
command.
This command will take a url
parameter, in either of two formats, HTTP or HTTPS. With this parameter, we will send a request to the url
and see if it's accessible.
To grab the parameter we call getParam
on our $input
and specify which parameter we want. Let's store our url
parameter in a $url
variable, or default to null
.
With this we can sent a error
output using getPrinter
and exit early if no url
was provided.
$url = $input->getParam('url') ?? null;
if (! $url) {
$app->getPrinter()->error('Parameter <url> was not provided');
return 1;
}
Now we can continue on and validate the incoming $url
parameter. To do that we will use RegEx and filter_var
.
We first check for a valid URL - since URLs can be valid even without the HTTP protocol, we add this check first. Returning early is the check fails.
Next we use RegEx to check if the $url
provided starts with a valid HTTP(s) protocol. Returning early with a message if that fails.
if (! filter_var($url, FILTER_VALIDATE_URL)) {
$app->getPrinter()->error('Parameter <url> not a valid URL.');
return 1;
}
if (! preg_match('#^https?://#i', $url)) {
$app->getPrinter()->error('Parameter <url> has to include a valid HTTP protocol.');
return 1;
}
While this isn't the end-all be-all of validating the $url
, it'll do for a simple ping command.
A streaming context
Before we try and access the $url
provided, we need to create a stream context for file_get_contents
to use. In this context we will set the HTTP method and some HTTP headers.
To keep things a bit separated, let's create a new function called getStreamContext
where we'll create our new context.
function getStreamContext() {
$headers = implode("\r\n", [
'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_16_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.77 Safari/537.36',
'Accept: text/html,application/xhtml+xml,application/xml;q=0.9',
'Accept-Language: en-US,en;q=0.9',
'Upgrade-Insecure-Requests: 1',
'X-Application: PingCLI/0.0.1',
'Sec-GPC: 1',
]);
return stream_context_create([
'http' => [
'method' => 'GET',
'header' => $headers,
]
]);
}
We set some headers so the $url
we're accessing thinks the site is being used from a Chrome browser running on a Mac.
Finishing up the command.
With the context created we can now use file_get_contents
to ping the $url
. Since we won't use the returning content for anything, we can use file_get_contents
directly in our if statement.
if (! @file_get_contents($url, context: getStreamContext())) {
$app->getPrinter()->error('Parameter <url> could not be reached.');
return 1;
}
The reasoning being the silencing (@) is because we can provide a valid URL that file_get_contents
might not be able to access, that will give of warnings unless silenced.
If all those checks are cleared, we can safely assume the site is reachable and up. Let's give the user an indication the site was reached by adding the following code to the end of our callable
.
$app->getPrinter()->success(sprintf('URL <%s> is up.', $url));
We can now test our ping command by running the following.
./bin/ping-cli ping url=https://devdojo.com
This will produce the following result.
Extending our command.
Before I leave you, I'd like to add one more feature to our command. That's the estimated ping time, which is an estimate of how long it took to access the website.
We'll do this with the microtime
function and some subtraction. We'll Add the following right above our file_get_contents
check.
$start_time = microtime(as_float: true);
Below our if, and before we output our success message we add the following.
$end_time = microtime(as_float: true);
These two variables will now be used to estimate how long it took to access the site. Since they're places in between file_get_contents
we should get a fairly close estimate.
Let's print that estimate to our user below out success output.
$app->getPrinter()->display(sprintf('Est. ping time: %.02f sec', ($end_time - $start_time)));
This will now add an estimated ping time to the end of our output, as displayed below.
Conclusion.
This is how you can create a simple CLI tool with the help of MiniCLI. You can read up more about minicli
on their GitHub page, or their documentation, also follow the creator Erika Heidi on twitter.
That's all for me folks, thank you for reading. π
Complete source available on my ping-cli
repository.
Troubleshooting.
If you're having issues running your new CLI tool, make sure the permissions are turned on to use the file as an executable. On Linux system this can be done with chmod
, use the equivalent command for windows.
ping-cli ~ chmod +x bin/ping-cli
Top comments (0)