1	<?php
2
3	declare(strict_types=1);
4
5	namespace Celemas\Cli;
6
7	/**
8	* Parses a command's argument tokens into options and positionals.
9	*
10	* Options use `--key=value` and repeat: `--tag=a --tag=b`. A dashed token
11	* without `=`, such as `--force` or `-h`, is a boolean flag. Every other
12	* token is a positional. Unlike PHP's native `getopt`, this reads an
13	* explicit token list, so the command name never interferes with parsing.
14	*
15	* A positional cannot start with `-`; such a token is read as a flag.
16	*
17	* @api
18	*/
19	final class Args
20	{
21	/** @var array<string, list<string>> */
22	private array $options = [];
23
24	/** @var list<string> */
25	private array $positionals = [];
26
27	/**
28	* @param list<string> $tokens
29	*/
30	public function __construct(array $tokens = [])
31	{
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
48	}
49	}
50
51	public function has(string $key): bool
52	{
53	return array_key_exists($key, $this->options);
54	}
55
56	public function opt(string $key, string $default = ''): string
57	{
58	return $this->options[$key][0] ?? $default;
59	}
60
61	/**
62	* @param list<string> $default
63	* @return list<string>
64	*/
65	public function opts(string $key, array $default = []): array
66	{
67	$values = $this->options[$key] ?? [];
68
69	return $values === [] ? $default : $values;
70	}
71
72	public function positional(int $index, ?string $default = null): ?string
73	{
74	return $this->positionals[$index] ?? $default;
75	}
76
77	/**
78	* @return list<string>
79	*/
80	public function positionals(): array
81	{
82	return $this->positionals;
83	}
84	}

---

Paths

Below are the source code lines that represent each code path as identified by Xdebug. Please note a path is not necessarily coterminous with a line, a line may contain multiple paths and therefore show up more than once. Please also be aware that some paths may include implicit rather than explicit branches, e.g. an if statement always has an else as part of its logical flow even if you didn't write one.

Args->__construct

30	public function __construct(array $tokens = [])
31	{
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
48	}
49	}

30	public function __construct(array $tokens = [])
31	{
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
48	}
49	}

30	public function __construct(array $tokens = [])
31	{
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
48	}
49	}

30	public function __construct(array $tokens = [])
31	{
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
48	}
49	}

30	public function __construct(array $tokens = [])
31	{
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
48	}
49	}

30	public function __construct(array $tokens = [])
31	{
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
48	}
49	}

30	public function __construct(array $tokens = [])
31	{
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
48	}
49	}

30	public function __construct(array $tokens = [])
31	{
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
48	}
49	}

30	public function __construct(array $tokens = [])
31	{
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
48	}
49	}

30	public function __construct(array $tokens = [])
31	{
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
33	if (!str_starts_with($token, '-')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
39	if (str_contains($token, '=')) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
48	}
49	}

30	public function __construct(array $tokens = [])
31	{
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
48	}
49	}

30	public function __construct(array $tokens = [])
31	{
32	foreach ($tokens as $token) {
32	foreach ($tokens as $token) {
33	if (!str_starts_with($token, '-')) {
34	$this->positionals[] = $token;
35
36	continue;
37	}
38
39	if (str_contains($token, '=')) {
40	/** @var array{0: string, 1: string} $pair */
41	$pair = explode('=', $token, limit: 2);
42	$this->options[$pair[0]][] = $pair[1];
43
44	continue;
45	}
46
47	$this->options[$token] ??= [];
48	}
49	}

Args->has

51	public function has(string $key): bool
52	{
53	return array_key_exists($key, $this->options);
54	}

Args->opt

56	public function opt(string $key, string $default = ''): string
57	{
58	return $this->options[$key][0] ?? $default;
59	}

Args->opts

65	public function opts(string $key, array $default = []): array
66	{
67	$values = $this->options[$key] ?? [];
68
69	return $values === [] ? $default : $values;
69	return $values === [] ? $default : $values;
69	return $values === [] ? $default : $values;
70	}

65	public function opts(string $key, array $default = []): array
66	{
67	$values = $this->options[$key] ?? [];
68
69	return $values === [] ? $default : $values;
69	return $values === [] ? $default : $values;
69	return $values === [] ? $default : $values;
70	}

Args->positional

72	public function positional(int $index, ?string $default = null): ?string
73	{
74	return $this->positionals[$index] ?? $default;
75	}

Args->positionals

82	return $this->positionals;
83	}