PHPackages                             weew/console-arguments - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. weew/console-arguments

ActiveLibrary[CLI & Console](/categories/cli)

weew/console-arguments
======================

Flexible console arguments parser.

v1.13.0(9y ago)125911MITPHP

Since Apr 6Pushed 9y ago1 watchersCompare

[ Source](https://github.com/weew/console-arguments)[ Packagist](https://packagist.org/packages/weew/console-arguments)[ RSS](/packages/weew-console-arguments/feed)WikiDiscussions master Synced today

READMEChangelogDependencies (6)Versions (21)Used By (1)

Console arguments parser
========================

[](#console-arguments-parser)

[![Build Status](https://camo.githubusercontent.com/32452bda2822b23e7914158ec79197971c5b2b5d404589b5b316f9638b402d61/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f776565772f636f6e736f6c652d617267756d656e74732e737667)](https://travis-ci.org/weew/console-arguments)[![Code Quality](https://camo.githubusercontent.com/11ef23bb80abca6fcb19a22cf6321c9bba0acf9e06e52f278150a7de076551dc/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f776565772f636f6e736f6c652d617267756d656e74732e737667)](https://scrutinizer-ci.com/g/weew/console-arguments)[![Test Coverage](https://camo.githubusercontent.com/be0cf01c87174d758b5507bd2a6460be1225855646e0183d02952a8844685848/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f776565772f636f6e736f6c652d617267756d656e74732e737667)](https://coveralls.io/github/weew/console-arguments)[![Version](https://camo.githubusercontent.com/96162eeede536c5dc2bbace63f744fde9b3e874dc669836a13ef6123155e9a53/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f776565772f636f6e736f6c652d617267756d656e74732e737667)](https://packagist.org/packages/weew/console-arguments)[![Licence](https://camo.githubusercontent.com/8e5ed973f988bb70c2b2308469ecca443b23454355570d50582ba9baf8c5d7d1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f776565772f636f6e736f6c652d617267756d656e74732e737667)](https://packagist.org/packages/weew/console-arguments)

Table of contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Introduction](#introduction)
- [Parsing arguments](#parsing-arguments)
- [Matching arguments](#matching-arguments)
- [Strict mode](#strict-mode)

Installation
------------

[](#installation)

`composer require weew/console-arguments`

Introduction
------------

[](#introduction)

This package allows you to easily build commands with certain expectations and then match them against a set of console arguments. It consists of two major parts, a `ArgumentsParser` and `ArgumentsMatcher`.

Note: this package has not been tested on windows.

Parsing arguments
-----------------

[](#parsing-arguments)

Arguments parser allows you to parse console arguments and takes care of many annoying things like quotes, equitation signs, combined flags etc. The parsing process consists of two steps. The first step is all about normalization and separation of arguments into pieces. The second one is for grouping of flags and options. Lets take a look at this example:

```
$parser = new ArgumentsParser();
// returns ['command:name', 'arg1', 'arg2', '--flag', 'custom "value', '-f', '1+1=2', '-v', '-v', '-v'];
$args = $parser->parse('command:name arg1 arg2 --flag="custom \"value" -f="1+1=2" -vvv');
```

Now you can groups these arguments.

```
// returns ['arguments' => ['command:name', 'arg1', 'arg2'], 'options' => ['--flag' => 1, '-f' => 1, '-v' => 1], '--flag' => ['custom "value'], '-f' => ['1+1=2'], '-v' => []]
$parser->group($args);
```

Depending on what kind of arguments you're working with, you might need grouped or ungrouped arguments to extract all the necessary information.

If your arguments are in form of an array instead of a string, simply do `implode(' ', $args)`. Be careful with the `$argv` arguments. First value in there is the path of the script and you need to remove it `array_unshift($args)`.

Matching arguments
------------------

[](#matching-arguments)

So now you have arguments. But working with plain arrays, ensuring that certain values are set etc. is quite annoying. Lets make it easy.

```
$command = new Command('name', 'description');

// create an arguments
$command->argument(ArgumentType::SINGLE, 'argument');

// create an option
$command->option(OptionType::SINGLE_OPTIONAL, '--color', '-c')
    ->setDefaultValue('red')
    ->setDescription('your favorite color');
```

You can also create arguments and options like this.

```
$argument = new Argument(ArgumentType::SINGLE, 'argument');
$command->addArgument($argument);

$option = new Option(OptionType::SINGLE, '--color', '-c');
$option
    ->setDefaultValue('red')
    ->setDescription('your favorite color');
$command->addOption($option);
```

There are several kinds of arguments and options.

```
// a single argument that must be set
// throws an error otherwise
ArgumentType::SINGLE;

// an optional argument
// no error will be thrown if missing
ArgumentType::SINGLE_OPTIONAL;

// takes a flexible amount of values
// at least one value must be set
// throws an error otherwise
ArgumentType::MULTIPLE;

// takes a flexible amount of values
// wont throw any errors
ArgumentType::MULTIPLE_OPTIONAL;

// a single argument is expected
// throws an error if option or value is missing
// can be used like this:
// -o arg results in -o=arg
OptionType::SINGLE;

// a single argument is expected
// will not throw any errors if option
// or value is missing
// -o results in -o=null
// -o arg results in -o=arg
OptionType::SINGLE_OPTIONAL;

// flexible amount of arguments is expected
// will throw an error if option
// or at least one value is missing
// can be used like this:
// -o arg1 arg2 arg3 results in -o=[arg1, arg2, arg3]
OptionType::MULTIPLE;

// flexible amount of arguments is expected
// will not throw any errors if option or
// value is missing
// can be used like this:
// -o results in -o=[]
// -o arg1 arg2 arg3 results in -o=[arg1, arg2, arg3]
OptionType::MULTIPLE_OPTIONAL;

// expects no value or one of these values:
// true, false, 0 or 1
// defaults to false
// will not throw any errors if missing
// can be used like this:
// -o results in -o=true
// -o=true|false|0|1 results in true or false
OptionType::BOOLEAN;

// expects a numeric value or no value at all
// defaults to 0
// wont throw any errors
// can be used like this:
// -ooo results in -o=3
// -o -oo results in -o=3
// -o=3 results in -o=3
OptionType::INCREMENTAL;
```

As soon as you have some commands defined, you can match them against the arguments. Matcher will throw exceptions if command expectations were not matched.

```
$args = $parser->parse('command arg1 arg2 --option');
$groupedArgs = $parser->group($args);
$matcher = new ArgumentsMatcher();

$command = $matcher->matchCommand($command, $groupedArgs);

$command->findArgument('arg')->getValue();
$command->findOption('--option')->getValue();
```

If you have multiple commands and don't know which should be used, you can let the matcher find it based on the command name. First value inside the arguments array is assumed to be a command name. Command name is matched intelligently. So a command with name `command` will match `command` as well as `c` and `com`. If multiple commands qualify for the same name, an exceptions will be thrown.

```
list($command, $groupedArgs) = $matcher->matchCommands($commands, $groupedArgs);
```

You can also match only an option or an argument the same way, just use `matchArgument` and `matchOption` methods.

Strict mode
-----------

[](#strict-mode)

By default, arguments matcher runs in strict mode. This means that if a command receives to many arguments or unknown options, an exception will be thrown. This behaviour can be disabled though.

```
list($command, $groupedArgs) = $matcher->matchCommands($commands, $groupedArgs, false);
```

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity14

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity72

Established project with proven stability

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~13 days

Recently: every ~44 days

Total

20

Last Release

3477d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/10b2b854b5829dd13a15967c000ed2119b5faef67aca24d94c653c8ac550d85e?d=identicon)[weew](/maintainers/weew)

### Embed Badge

![Health badge](/badges/weew-console-arguments/health.svg)

```
[![Health](https://phpackages.com/badges/weew-console-arguments/health.svg)](https://phpackages.com/packages/weew-console-arguments)
```

###  Alternatives

[seld/cli-prompt

Allows you to prompt for user input on the command line, and optionally hide the characters they type

24726.4M22](/packages/seld-cli-prompt)[illuminate/console

The Illuminate Console package.

13045.3M6.2k](/packages/illuminate-console)[magento/magento2-functional-testing-framework

Magento2 Functional Testing Framework

15311.8M36](/packages/magento-magento2-functional-testing-framework)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)