danbettles/command-line-tools

Comprises just a few basic classes that make it easier to write command-line scripts. Use this when the might of something like Symfony Console would be like taking a sledgehammer to a thumbtack.

Maintainers

Details

github.com/danbettles/command-line-tools

Source

Issues

Installs: 1

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 2

Forks: 0

Open Issues: 0

v1.0.0-beta.1 2022-11-17 13:57 UTC

Requires

  • php: ^7.4|^8.1.3

Requires (Dev)

ISC ab899d46525740a9d09ff76679f8463b2608701b

  • Daniel Bettles <danbettles.woop@yahoo.co.uk>

This package is auto-updated.

Last update: 2024-04-26 00:16:38 UTC

README

Skip to installation instructions.

This library comprises just a few basic classes that make it easier to write command-line PHP scripts. There are helpers for running external programs, and methods for sending formatted messages to the output. Use this library when the might of something like Symfony Console would be like taking a sledgehammer to a thumbtack.

The main component classes are Output, MessageFormatter, and Host.

Output

Displays messages on the screen; it provides methods that output messages in different styles.

For example:

(new Output())->writeLine('A plain-looking message followed by a newline.');

(new Output())->danger('A brightly-coloured message about something that just went wrong, followed by a newline.');

Run php tests/show_output_formats.php to see what Output can do.

MessageFormatter

Provides a fluent interface for creating formatted messages. It uses a CSS-like approach, using CSS naming conventions whenever possible, to make the job easier, more intuitive, for web developers.

For example, both of the following calls will create the same bold white message on a bright red background.

$formattedMessage = (new MessageFormatter())
    ->fontWeight('bold')
    ->backgroundColor('maroon')
    ->format('A brightly-coloured message about something that just went wrong')
;

$formattedMessage = MessageFormatter::createFromStyleDeclarations([
    'font-weight' => 'bold',
    'background-color' => 'maroon',
])->format('A brightly-coloured message about something that just went wrong');

When creating a Formatter from an array of style declarations, you can use either CSS-style kebab-case names or camel-case names.

MessageFormatter will automatically use a contrasting colour for the foreground if only the background colour is set.

See the section on the available styles, below, to see what you can do.

Style Reference

Property Formatter Method Valid Values
visibility1 visibility hidden|visible
font-weight fontWeight normal|bold|thin2
font-style fontStyle normal|italic1
text-decoration textDecoration none|underline
color3 color initial|teal|aqua|black|gray|navy|blue|purple|fuchsia|green|lime|maroon|red|olive|yellow|silver|white
background-color3 backgroundColor initial|teal|aqua|black|gray|navy|blue|purple|fuchsia|green|lime|maroon|red|olive|yellow|silver|white

Run php tests/show_styles.php to see the effect of each of the style settings—and whether or not a style is supported by your terminal.

Host

Provides a helpful passthru() wrapper that echoes the command it's executing in addition to its output, and, by default, throws an exception if something goes wrong.

For example:

$output = new Output();
$host = new Host($output);

// Throws an exception if something goes wrong.
$host->passthru('ls -al --color=always');

// Will not throw an exception if something goes wrong: instead, will display a formatted error message and return a value indicating the problem that occurred.
$resultCode = $host->passthru('ls -al --color=always', false);

Installation

No dependencies other than PHP 7+.

Install using Composer by running composer require danbettles/command-line-tools.

References

Footnotes

  1. Not widely supported by terminals. ↩ ↩2

  2. Non-standard name. ↩

  3. Responds to CSS Level-1 named colours. ↩ ↩2