Download the PHP package nette/command-line without Composer

Nette Command-Line

A lightweight library for building command-line applications in PHP. It provides:

• Argument parsing with switches, options, and positional arguments
• Colorful terminal output with ANSI support

Install it using Composer:

It requires PHP version 8.2 and supports PHP up to 8.5.

If you like Nette, please make a donation now. Thank you!

Parsing Command-Line Arguments

Every CLI script needs to handle arguments like --verbose, -o output.txt, or plain file names. The Parser class offers the fastest way to get started: just write your help text and let the parser extract option definitions from it:

That's it. The parser understands that --verbose is a switch, --output requires a value, --format has an optional value with json as fallback. Your help text stays in sync with actual option definitions.

The parse() method returns an associative array. Keys match option names exactly as defined, including the dashes:

By default, parse() reads from $_SERVER['argv']. You can pass a custom array for testing:

Help Text Syntax

The parser extracts option definitions from formatted help text:

Each line defines one option. Option names must be separated from descriptions by at least two spaces.

Additional Configuration

Some settings can't be expressed in help text. Pass an array as the second parameter, keyed by option name:

Available keys:

Fluent API

When you need more control over option definitions, use the fluent API with addSwitch(), addOption(), and addArgument() methods. This approach gives you access to all features including normalizers, enums, and precise control over each parameter:

By default, parse() reads from $_SERVER['argv']. You can pass a custom array for testing:

Switches, Options, and Arguments

There are three types of command-line inputs:

Switches are flags without values, like --verbose or -v. They parse as true when present, null when absent:

Options accept values, like --output file.txt. The value can be separated by space or =:

Note that the option itself is always optional - not using it returns null. However, when used, the value is required by default. Set optionalValue: true to allow the option without a value (parses as true):

When the same option is used multiple times without repeatable: true, the last value wins:

Arguments are positional values without dashes. By default they are required. Set optional: true to make them optional:

Use fallback to specify the value when an option or argument is not provided. For options with optionalValue: true, note that using the option without a value still parses as true, while the fallback is used only when the option is not present at all:

Arguments can appear anywhere on the command line - they don't have to come after options:

Restricting Values with Enum

Limit accepted values to a specific set:

Repeatable Options

Set repeatable: true to collect multiple values into an array:

Transforming Values

Use normalizer to transform parsed values:

For file path validation, use the built-in normalizeRealPath:

Mixing Both Approaches

You can combine addFromHelp() with fluent methods when you need normalizers for some options:

Error Handling

The parser throws \Exception for invalid input:

Common error messages:

Use isEmpty() to check if no command-line arguments were provided (i.e., user ran just script.php with nothing after it):

Handling --help and --version

When your script has required arguments, running script.php --help would normally fail because the required argument is missing. Use parseOnly() to check for info options first:

The parseOnly() method:

• Parses only the specified options, ignoring everything else
• Respects aliases (-h → --help)
• Never throws exceptions
• Returns null for options that weren't used

Complete Example

Here's a real-world file converter script combining Parser and Console:

The script accepts commands like:

• convert input.txt - convert with defaults
• convert -v --format xml input.txt - verbose, XML format
• convert -o result.txt input.txt - specify output file
• convert --help - show help (works even without input file)