Phargs

Phargs is a toolkit for writing CLI scripts in PHP; it was born out of frustration, anger, and boilerplate déjà vu. Pull requests, issues, and suggestions are always welcome.

Phargs' main asset is its argument processor, but the output tools are pretty useful too.

Everything in Phargs is available through \Phargs\Factory.

This README file is a little long, so here's a breakdown of the contents:

Installation
Argument processing
Outputting to the screen
- Basic usage
- Colors
Prompting for input
- Basic usage
- Required input
Formatting
- Tables
- TSV
Requirements
Testing

Installation

Phargs is available on Packagist so you can install it using Composer. Just specify it as a dependency in your composer.json:

{
    "require": {
        "tomnomnom/phargs": "0.0.5"
    }
}

Then run composer install:

▶ composer install
Loading composer repositories with package information
Installing dependencies
  - Installing tomnomnom/phargs (0.0.2)
    Loading from cache

Writing lock file
Generating autoload files

Once installed you can use the composer autoloader instead of the Phargs/Init.php script that the included examples use:

<?php
require __DIR__.'/vendor/autoload.php';

$factory = new \Phargs\Factory();
$screen = $factory->screen();

$screen->outln("Hello, World!");

Argument processing

The getopt interface isn't the most friendly thing in the world, Phargs tries to make your life a bit easier.

The argument processor is available via \Phargs\Factory::args().

Flags

A flag is an argument that turns functionality on or off. Common examples are -h to display a help message or --verbose to display more output.

Basic usage

Phargs needs to be told to expect a flag in order to use it.

<?php
// ./Examples/Flags.php

// Bootstrap Phargs
include __DIR__.'/../Phargs/Init.php';

// Everything in Phargs is available via the Factory
$factory = new \Phargs\Factory();

// Get an argument processor
$args = $factory->args();

// Expect the -h flag to be an argument
$args->expectFlag('-h');

if ($args->flagIsSet('-h')){
  echo "Help flag is set\n";
} else {
  echo "Help flag is not set";
}

▶ php ./Examples/Flags.php -h
Help flag is set
▶ php ./Examples/Flags.php
Help flag is not set

Flag aliases

You can alias flags to make your script more user friendly. Phargs supports both long (e.g. --help) and short (e.g. -h) flags.

<?php
// ./Examples/FlagAliases.php

include __DIR__.'/../Phargs/Init.php';
$factory = new \Phargs\Factory();
$args = $factory->args();

$args->expectFlag('-h');

// Alias the -h flag to --help so either can be used
$args->addFlagAlias('-h', '--help');

// You could check for --help instead of -h here and it would still work
if ($args->flagIsSet('-h')){
  echo "Help flag is set\n";
} else {
  echo "Help flag is not set\n";
}

▶ php ./Examples/FlagAliases.php -h
Help flag is set
▶ php ./Examples/FlagAliases.php --help
Help flag is set

Compound flags

Phargs also supports compound flags; like how you might run grep -Hnr $searchString *.

<?php
// ./Examples/CompoundFlags.php

include __DIR__.'/../Phargs/Init.php';
$factory = new \Phargs\Factory();
$args = $factory->args();

$args->expectFlag('-H');
$args->expectFlag('-n');
$args->expectFlag('-r');

if ($args->flagIsSet('-H')){
  echo "-H flag is set\n";
}
if ($args->flagIsSet('-n')){
  echo "-n flag is set\n";
}
if ($args->flagIsSet('-r')){
  echo "-r flag is set\n";
}

▶ php ./Examples/CompoundFlags.php -Hnr
-H flag is set
-n flag is set
-r flag is set
▶ php ./Examples/CompoundFlags.php -H -nr
-H flag is set
-n flag is set
-r flag is set
▶ php ./Examples/CompoundFlags.php -Hni # Note: 'i' is unexpected
-H flag is set
-n flag is set
▶ php ./Examples/CompoundFlags.php -n -r
-n flag is set
-r flag is set

Params

A param is an argument that provides a value. They come in 4 flavours:

Long, with an equals (e.g. --count=5)
Long, with a space (e.g. --count 5)
Short, with a space (e.g. -c 5)
Short, without a space (e.g. -c5)

Basic usage

Like with flags, you must tell Phargs to expect a param. Unlike flags, you can also get the value of a param:

<?php
// ./Examples/Params.php

// Bootstrap Phargs
include __DIR__.'/../Phargs/Init.php';

// Everything in Phargs is available via the Factory
$factory = new \Phargs\Factory();

// Get an argument processor
$args = $factory->args();

// Expect the --count param
$args->expectParam('--count');

if ($args->paramIsSet('--count')){
  echo "--count param is set\n";
  echo "--count value is: ";
  echo $args->getParamValue('--count').PHP_EOL;
} else {
  echo "--count param is not set\n";
}

▶ php ./Examples/Params.php --count=5
--count param is set
--count value is: 5
▶ php ./Examples/Params.php --count 5
--count param is set
--count value is: 5
▶ php ./Examples/Params.php --help
--count param is not set

Param aliases

Like flags, params can be aliased:

<?php
// ./Examples/ParamAliases.php

include __DIR__.'/../Phargs/Init.php';
$factory = new \Phargs\Factory();
$args = $factory->args();

// Expect the --count param
$args->expectParam('--count');

// Alias --count to -c so that either can be used
$args->addParamAlias('--count', '-c');

if ($args->paramIsSet('--count')){
  echo "--count param is set\n";
  echo "--count value is: ";
  echo $args->getParamValue('-c').PHP_EOL;
} else {
  echo "--count param is not set\n";
}

▶ php ./Examples/ParamAliases.php --count=5
--count param is set
--count value is: 5
▶ php ./Examples/ParamAliases.php -c 5
--count param is set
--count value is: 5
▶ php ./Examples/ParamAliases.php -c5
--count param is set
--count value is: 5

Required params

In the examples so far Phargs has expected to see params, but it doesn't mind if they're not there. If a param is important enough you can require that it exists and then check that all requirements are met:

<?php
// ./Examples/RequiredParams.php

include __DIR__.'/../Phargs/Init.php';
$factory = new \Phargs\Factory();
$args = $factory->args();

// Require some params
$args->requireParam('--count');
$args->requireParam('--number');

// Check that all argument requirements are met
if ($args->requirementsAreMet()){
  echo "All arg requirements are met\n";
} else {
  echo "Not all arg requirements are met\n";
}

▶ php ./Examples/RequiredParams.php --count=4 --number=5
All arg requirements are met
▶ php ./Examples/RequiredParams.php --count=4 
Not all arg requirements are met

Residual args

Residual args are the arguments left over when expected params and flags have been removed. For example:

./command -v help merge

Assuming the -v flag is expected by Phargs: help and merge are considered to be residual args. Residual args are zero-indexed, and their indexes remain the same regardless of where any expected flags or params appear in the argument list.

You can get one, all, or a range of residual args:

<?php
// ./Examples/ResidualArgs.php

include __DIR__.'/../Phargs/Init.php';
$factory = new \Phargs\Factory();
$args = $factory->args();

// We're expecting some arguments
$args->expectParam('--count');
$args->expectFlag('-h');

// Arguments we're not expecting are considered 'residual'
echo "Residual arg #0: ".$args->getResidualArg(0).PHP_EOL;
echo "All residual args: ".implode(', ', $args->getResidualArgs()).PHP_EOL;
echo "First two residual args: ".implode(', ', $args->getResidualArgs(0, 2)).PHP_EOL;

▶ php ./Examples/ResidualArgs.php -h help merge
Residual arg #0: help
All residual args: help, merge
First two residual args: help, merge
▶ php ./Examples/ResidualArgs.php help -h merge
Residual arg #0: help
All residual args: help, merge
First two residual args: help, merge
▶ php ./Examples/ResidualArgs.php help -h merge this thing
Residual arg #0: help
All residual args: help, merge, this, thing
First two residual args: help, merge

Outputting to the screen

Phargs provides an interface for outputting text to the screen.

The screen interface is available via \Phargs\Factory::screen().

Basic usage

Amongst other things, the screen interface provides methods to write to stdout and stderr, with or without trailing newline characters. It also provides some methods that are useful when debugging.

<?php
// ./Examples/ScreenBasic.php

include __DIR__.'/../Phargs/Init.php';
$factory = new \Phargs\Factory();

// Get a screen interface
$screen = $factory->screen();

$screen->out("Hello, ");
$screen->outln("World!");

$screen->err("Error ");
$screen->errln("message");

$screen->printf("When in %s".PHP_EOL, "Rome");

$testVar = array(1, 2, 3);
$screen->varExport($testVar);

$screen->log('A log message');

▶ php ./Examples/ScreenBasic.php 
Hello, World!
Error message
When in Rome
array (
  0 => 1,
  1 => 2,
  2 => 3,
)
2012-12-22T15:16:50+00:00: A log message

Colors

Although dif

Phargs

Install / Use

README

Phargs

Contents

Installation

Argument processing

Flags

Basic usage

Flag aliases

Compound flags

Params

Basic usage

Param aliases

Required params

Residual args

Outputting to the screen

Basic usage

Colors