README

ZeroConfig CLI is a set of CLI tools, written in PHP, that require zero configuration in order to function.

This package aims to provide a set of convenience methods to create CLI tooling without having to set up a framework or having in-depth knowledge of the inner workings of PHP CLI.

By design, it solves how to deal with large data streams. It is based on data going in, data being manipulated and then data going out. Whether the source is piped data, a local file or HTTP resource, it will be streamed line by line.

Transformation of data also occurs line by line, going in and coming out. The same goes for output, whether it's written to a file or STDOUT.

If an application is assembled using components from this library, your application will hold only one line of resource data in memory, at any given moment. This WILL reduce memory consumption and is a sure fire way to keep performance high in most CLI solutions.

Installation

To install the code base on which the tools are built, as a library:

composer require zero-config/cli

Alternatively, a built executable can be downloaded as zc.phar.

Correct execution rights and put it somewhere in your path:

chmod +x zc.phar
sudo ln -s /path/to/zc.phar /usr/bin/zc

I/O

The I/O is easily handled by the input and output components of the package.

Input

Input sources are implemented as generators and can thus be used to stream data line by line.

<?php
use ZeroConfig\Cli\Reader\StandardIn;

$pipe = new StandardIn();

// Echo what is piped to the application.
foreach ($pipe as $line) {
    echo $line;
}

Resource	Description
File	Read files from the local filesystem.
Gzip	Read Gzip archives, like backups of databases or logs.
STDIN	Read piped data streams.
HTTP	Stream web resources.
Callback	Stream data using a callback.

Output

Output writers expect iterable data and are able to write data line by line; ideal for handling streaming data.

<?php
use ZeroConfig\Cli\Writer\File;
use ZeroConfig\Cli\Reader\ReaderInterface;

$writer = new File('The.Zookeeper\'s.Wife.mp4');

/** @var ReaderInterface $movie */
$writer($movie);

Writer	Description
File	Write to a file on the local filesystem.
STDOUT / STDERR	Write to the console.
Callback	Write to a callable handle.
CSV	Write to CSV files.

Transformers

Transformers can be used to reduce, modify or enrich the data between input and output.

The following is an example of the match filter. It makes use of PCRE patterns.

<?php
use ZeroConfig\Cli\Transformer\Pcre\MatchFilter;

$transformer = new MatchFilter('/[Bb]a[rz]/');
$input       = [
    'This is foo!',
    'Greetings from bar :)',
    'A wonderful day from baz.'
];

foreach ($transformer($input) as $line) {
    echo $line . PHP_EOL;
}

The above example will output:

Greetings from bar :)
A wonderful day from baz.

The following are available transformers.

Group	Transformer	Description
Sequence	SkipFilter	Skip a set number of records.
Sequence	LimitFilter	Limit the number of records to a set amount.
String	ContainsFilter	Match input that contains a substring.
String	LineEnding	End strings with newlines or configurable sequences.
PCRE	MatchFilter	Input must match a given PCRE pattern.
PCRE	ReplaceFilter	Replace input using a PCRE pattern.
CSV	CsvParser	Parse CSV strings into (associative) arrays.
Callback	CallbackTransformer	Create a custom transformer using a callback.

Chaining transformers

While transformers can be chained by wrapping one transformer into the other, a convenience transformer chain is available to easily chain transformers.

zero-config / cli

Maintainers

Details