Download the PHP package tomnomnom/phargs without Composer

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.

Contents

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

• Installation
• Argument processing
  • Flags - Intro
  • Flags - Basic usage
  • Flags - Flag aliases
  • Flags - Compound flags
  • Params - Intro
  • Params - Basic usage
  • Params - Param aliases
  • Params - Required params
  • Residual args
• 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:

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:

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 -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 -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 -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 --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 --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 --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 -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 
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 difficult to demonstrate in a README file, Phargs supports ANSI colors.

▶ php ./Examples/ScreenColors.php 
Red
Red with a white background
Red with a white background, underlined

They really are in color; honest!

8 colors are supported:

• black
• red
• green
• yellow
• blue
• purple
• cyan
• white

3 different styles are supported:

• regular
• bold
• underline

Prompting for input

Phargs has an interface for prompting for user input.

The prompter is available via \Phargs\Factory::prompter().

Basic usage

The prompt method can be used to prompt the user for some input. The trailing newline character is removed.

▶ php ./Examples/PrompterBasic.php 
What is your name? Tom
Hello, Tom!

Required input

You can also require that a user input some information, optionally displaying a message when they don't.

▶ php ./Examples/PrompterRequired.php 
What is your name? 
No name entered!
What is your name? Tom
Hello, Tom!

Formatting

Tables

The table formatter works out how wide to make each column so that everything lines up. It's available via \Phargs\Factory::table().

▶ php ./Examples/Table.php
--------------
| id | name  |
--------------
| 1  | Tom   |
| 2  | Dick  |
| 3  | Harry |
--------------

TSV

The TSV (Tab Separated Values) formatter is very similar to the Table formatter. It's available via \Phargs\Factory::tsv().

▶ php ./Examples/Tsv.php
id      name
1       Tom
2       Dick
3       Harry

Requirements

• Linux of some description
• PHP 5.3 or newer

Testing

You can run the full test suite by running:

▶ phpunit

The tests are actually split up into 3 suites, which can be run individually:

▶ phpunit --filter Unit
▶ phpunit --filter Integration
▶ phpunit --filter FullStack

The repo is hooked up to Travis CI. You can see the state of the master branch and the build history on the Phargs Travis CI page. The full test suite runs under PHP 5.3 and PHP 5.4.