{"id":15525286,"url":"https://github.com/donatj/flags","last_synced_at":"2025-04-15T11:07:52.247Z","repository":{"id":45591776,"uuid":"13310806","full_name":"donatj/Flags","owner":"donatj","description":"A GNU-style PHP command line argument parser inspired by Go's Flag package.","archived":false,"fork":false,"pushed_at":"2025-01-17T20:51:35.000Z","size":115,"stargazers_count":19,"open_issues_count":5,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-15T11:07:23.337Z","etag":null,"topics":["argument-parser","cli","cli-args","php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/donatj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2013-10-03T21:52:12.000Z","updated_at":"2025-01-17T20:43:10.000Z","dependencies_parsed_at":"2023-11-27T18:28:13.014Z","dependency_job_id":"9cbaf274-beaa-4c3d-afdf-ca6e84902419","html_url":"https://github.com/donatj/Flags","commit_stats":{"total_commits":100,"total_committers":6,"mean_commits":"16.666666666666668","dds":0.26,"last_synced_commit":"875afa9c0a54d5461f01fa9f8af4a53475f3977a"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatj%2FFlags","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatj%2FFlags/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatj%2FFlags/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatj%2FFlags/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/donatj","download_url":"https://codeload.github.com/donatj/Flags/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249058369,"owners_count":21205910,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["argument-parser","cli","cli-args","php"],"created_at":"2024-10-02T10:56:19.085Z","updated_at":"2025-04-15T11:07:52.228Z","avatar_url":"https://github.com/donatj.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flags\n\n[![Latest Stable Version](https://poser.pugx.org/donatj/flags/version)](https://packagist.org/packages/donatj/flags)\n[![Total Downloads](https://poser.pugx.org/donatj/flags/downloads)](https://packagist.org/packages/donatj/flags)\n[![License](https://poser.pugx.org/donatj/flags/license)](https://packagist.org/packages/donatj/flags)\n[![ci.yml](https://github.com/donatj/Flags/actions/workflows/ci.yml/badge.svg)](https://github.com/donatj/Flags/actions/workflows/ci.yml)\n\n\nFlags is an argument parser inspired by the Go-lang [Flag](http://golang.org/pkg/flag/#Parsed) package, taking its methodology but attaching a **GNU-style** flag parser.\n\n---\n\nFlags supports the following style of parameters:\n\nLong-Flags  \n`--key=value` / `--key value`\n\nShort-Flags  \n`-v`\n\nGNU Style Multi-Short-Flags  \n`-Xasd`\n\nMultiple of the Same Short-Flag  \n`-vvv`\n\nAs well as the ` -- ` operator for absolute separation of arguments from options.\n\n## Requirements\n\n- **php**: \u003e=7.1.0\n\n## Installing\n\nInstall the latest version with:\n\n```bash\ncomposer require 'donatj/flags'\n```\n\n## Example\n\nHere is a simple example script:\n\n```php\n\u003c?php\n\nrequire __DIR__ . '/../vendor/autoload.php';\n\n$flags = new donatj\\Flags();\n\n$foo     = \u0026 $flags-\u003ebool('foo', false, 'Enable the foo');\n$bar     = \u0026 $flags-\u003euint('bar', 10, 'Number of bars');\n$baz     = \u0026 $flags-\u003estring('baz', 'default', 'What to name the baz');\n$verbose = \u0026 $flags-\u003eshort('v', 'verbosity');\n\n/**\n * No Default value, making qux is *required*\n */\n$qux = \u0026 $flags-\u003ebool('qux');\n\ntry {\n\t$flags-\u003eparse();\n} catch( Exception $e ) {\n\tdie($e-\u003egetMessage() . PHP_EOL . $flags-\u003egetDefaults() . PHP_EOL);\n}\n```\n\nThe by-reference `= \u0026` allows the value to be updated from the *default* to the argument value once the `parse()` method has been triggered. This is inspired by the Go Flag packages use of pointers\n\n```\nbash-3.2$ php example/example.php\nExpected option --qux missing.\n        -v   verbosity\n     --foo   Enable the foo\n     --bar   [uint] Number of bars\n     --baz   [string] What to name the baz\n     --qux   \u003cbool\u003e\n\t\t\t\t\n```\n\n## Documentation\n\n### Class: donatj\\Flags\n\n#### Method: Flags-\u003e__construct\n\n```php\nfunction __construct([ ?array $args = null [, $skipFirstArgument = true]])\n```\n\nFlags constructor.\n\n##### Parameters:\n\n- ***array*** | ***null*** `$args` - The arguments to parse, defaults to $_SERVER['argv']\n- ***bool*** `$skipFirstArgument` - Setting to false causes the first argument to be parsed as an parameter\nrather than the command.\n\n---\n\n#### Method: Flags-\u003earg\n\n```php\nfunction arg($index)\n```\n\nReturns the n'th command-line argument. `arg(0)` is the first remaining argument after flags have been processed.\n\n##### Parameters:\n\n- ***int*** `$index`\n\n##### Returns:\n\n- ***string***\n\n---\n\n#### Method: Flags-\u003eargs\n\n```php\nfunction args()\n```\n\nReturns the non-flag command-line arguments.\n\n##### Returns:\n\n- ***string[]*** - Array of argument strings\n\n---\n\n#### Method: Flags-\u003eshorts\n\n```php\nfunction shorts()\n```\n\nReturns an array of short-flag call-counts indexed by character  \n  \n`-v` would set the 'v' index to 1, whereas `-vvv` will set the 'v' index to 3\n\n##### Returns:\n\n- ***array***\n\n---\n\n#### Method: Flags-\u003elongs\n\n```php\nfunction longs()\n```\n\nReturns an array of long-flag values indexed by flag name\n\n##### Returns:\n\n- ***array***\n\n---\n\n#### Method: Flags-\u003eshort\n\n```php\nfunction short($letter [, $usage = ''])\n```\n\nDefines a short-flag of specified name, and usage string.  \n  \nThe return value is a reference to an integer variable that stores the number of times the short-flag was called.  \n  \nThis means the value of the reference for v would be the following.  \n  \n    -v =\u003e 1  \n    -vvv =\u003e 3\n\n##### Parameters:\n\n- ***string*** `$letter` - The character of the short-flag to define\n- ***string*** `$usage` - The usage description\n\n##### Returns:\n\n- ***int***\n\n---\n\n#### Method: Flags-\u003ebool\n\n```php\nfunction bool($name [, $value = null [, $usage = '']])\n```\n\nDefines a bool long-flag of specified name, default value, and usage string.  \n  \nThe return value is a reference to a variable that stores the value of the flag.  \n\n##### Examples\n\n##### Truth-y\n\n     --mybool=[true|t|1]  \n     --mybool [true|t|1]  \n     --mybool  \n\n##### False-y\n\n     --mybool=[false|f|0]  \n     --mybool [false|f|0]  \n       [not calling --mybool and having the default false]\n\n##### Parameters:\n\n- ***string*** `$name` - The name of the long-flag to define\n- ***mixed*** `$value` - The default value - usually false for bool - which if null marks the flag required\n- ***string*** `$usage` - The usage description\n\n##### Returns:\n\n- ***mixed*** - A reference to the flags value\n\n---\n\n#### Method: Flags-\u003efloat\n\n```php\nfunction float($name [, $value = null [, $usage = '']])\n```\n\nDefines a float long-flag of specified name, default value, and usage string.  \n  \nThe return value is a reference to a variable that stores the value of the flag.  \n\n##### Examples\n\n    --myfloat=1.1  \n    --myfloat 1.1\n\n##### Parameters:\n\n- ***string*** `$name` - The name of the long-flag to define\n- ***mixed*** `$value` - The default value which if null marks the flag required\n- ***string*** `$usage` - The usage description\n\n##### Returns:\n\n- ***mixed*** - A reference to the flags value\n\n---\n\n#### Method: Flags-\u003eint\n\n```php\nfunction int($name [, $value = null [, $usage = '']])\n```\n\nDefines an integer long-flag of specified name, default value, and usage string.  \n  \nThe return value is a reference to a variable that stores the value of the flag.  \n  \nNote: Float values trigger an error, rather than casting.  \n\n##### Examples\n\n    --myinteger=1  \n    --myinteger 1\n\n##### Parameters:\n\n- ***string*** `$name` - The name of the long-flag to define\n- ***mixed*** `$value` - The default value which if null marks the flag required\n- ***string*** `$usage` - The usage description\n\n##### Returns:\n\n- ***mixed*** - A reference to the flags value\n\n---\n\n#### Method: Flags-\u003euint\n\n```php\nfunction uint($name [, $value = null [, $usage = '']])\n```\n\nDefines a unsigned integer long-flag of specified name, default value, and usage string.  \n  \nThe return value is a reference to a variable that stores the value of the flag.  \n  \nNote: Negative values trigger an error, rather than casting.  \n\n##### Examples\n\n    --myinteger=1  \n    --myinteger 1\n\n##### Parameters:\n\n- ***string*** `$name` - The name of the long-flag to define\n- ***mixed*** `$value` - The default value which if null marks the flag required\n- ***string*** `$usage` - The usage description\n\n##### Returns:\n\n- ***mixed*** - A reference to the flags value\n\n---\n\n#### Method: Flags-\u003estring\n\n```php\nfunction string($name [, $value = null [, $usage = '']])\n```\n\nDefines a string long-flag of specified name, default value, and usage string.  \n  \nThe return value is a reference to a variable that stores the value of the flag.  \n  \nExamples  \n  \n    --mystring=vermouth  \n    --mystring=\"blind jazz singers\"  \n    --mystring vermouth  \n    --mystring \"blind jazz singers\"\n\n##### Parameters:\n\n- ***string*** `$name` - The name of the long-flag to define\n- ***mixed*** `$value` - The default value which if null marks the flag required\n- ***string*** `$usage` - The usage description\n\n##### Returns:\n\n- ***mixed*** - A reference to the flags value\n\n---\n\n#### Method: Flags-\u003egetDefaults\n\n```php\nfunction getDefaults()\n```\n\nReturns the default values of all defined command-line flags as a formatted string.  \n\n##### Example\n\n```  \n           -v   Output in verbose mode  \n  --testsuite   [string] Which test suite to run.  \n  --bootstrap   [string] A \"bootstrap\" PHP file that is run before the specs.  \n       --help   Display this help message.  \n    --version   Display this applications version.  \n```\n\n##### Returns:\n\n- ***string***\n\n---\n\n#### Method: Flags-\u003eparse\n\n```php\nfunction parse([ ?array $args = null [, $ignoreExceptions = false [, $skipFirstArgument = null]]])\n```\n\nParses flag definitions from the argument list, which should include the command name.  \n  \nMust be called after all flags are defined and before flags are accessed by the program.  \n  \nWill throw exceptions on Missing Require Flags, Unknown Flags or Incorrect Flag Types\n\n##### Parameters:\n\n- ***array*** | ***null*** `$args` - The arguments to parse. Defaults to arguments defined in the constructor.\n- ***bool*** `$ignoreExceptions` - Setting to true causes parsing to continue even after an exception has been\nthrown.\n- ***bool*** `$skipFirstArgument` - Option to parse the first argument as an parameter rather than the command.\nDefaults to constructor value\n\n**Throws**: `\\donatj\\Exceptions\\MissingFlagParamException`\n\n**Throws**: `\\donatj\\Exceptions\\InvalidFlagParamException`\n\n**Throws**: `\\donatj\\Exceptions\\InvalidFlagTypeException`\n\n---\n\n#### Method: Flags-\u003eparsed\n\n```php\nfunction parsed()\n```\n\nReturns true if the command-line flags have been parsed.\n\n##### Returns:\n\n- ***bool***","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonatj%2Fflags","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdonatj%2Fflags","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonatj%2Fflags/lists"}