{"id":13410055,"url":"https://github.com/nategood/commando","last_synced_at":"2025-05-14T18:00:31.137Z","repository":{"id":4338180,"uuid":"5473917","full_name":"nategood/commando","owner":"nategood","description":"An Elegant CLI Library for PHP","archived":false,"fork":false,"pushed_at":"2024-05-07T08:18:32.000Z","size":194,"stargazers_count":796,"open_issues_count":34,"forks_count":80,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-05-05T21:36:30.091Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/nategood.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-08-19T20:11:06.000Z","updated_at":"2025-03-19T00:57:01.000Z","dependencies_parsed_at":"2024-06-18T10:50:41.663Z","dependency_job_id":"fb67b1a4-6569-4b80-8eb9-2b7e644c540c","html_url":"https://github.com/nategood/commando","commit_stats":{"total_commits":119,"total_committers":32,"mean_commits":3.71875,"dds":0.7226890756302521,"last_synced_commit":"08077a369f80687b24c88648735d5858ce7db5e9"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nategood%2Fcommando","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nategood%2Fcommando/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nategood%2Fcommando/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nategood%2Fcommando/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nategood","download_url":"https://codeload.github.com/nategood/commando/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253632847,"owners_count":21939377,"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":[],"created_at":"2024-07-30T20:01:04.718Z","updated_at":"2025-05-14T18:00:31.089Z","avatar_url":"https://github.com/nategood.png","language":"PHP","funding_links":[],"categories":["命令行","PHP","目录","Table of Contents","Command Line","命令行( Command Line )","命令行 Command Line"],"sub_categories":["命令行 Command Line","Command Line"],"readme":"# Commando\n\n## An Elegant PHP CLI Library\n\nCommando is a PHP command line interface library that beautifies and simplifies writing PHP scripts intended for command line use.\n\n## Why?\n\nPHP's `$argv` magic variable and global `$_SERVER['argv']` make me cringe, [`getopt`](http://php.net/manual/en/function.getopt.php) isn't all that much better, and most other PHP CLI libraries are far too bloated for many cases. Commando gets down to business without a ton of overhead, removes the common boilerplate stuff when it comes to handling CLI input, all while providing a clean and readable interface.\n\n## Installation\n\n_Commando requires that you are running PHP 8.1 or higher._\n\nCommando is [PSR-0](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md) compliant and can be installed using [Composer](http://getcomposer.org/). Add `nategood/commando` to your `composer.json`\n\n    \"require\": {\n        \"nategood/commando\": \"*\"\n    }\n\nIf you're new to Composer...\n\n- [Download and build Composer](http://getcomposer.org/download/)\n- Make it [globally accessible](http://getcomposer.org/doc/00-intro.md#globally)\n- `cd` to your the directory where you'll be writing your Commando script and run `composer install`\n\n_Currently installing via Composer is the only supported option._\n\n## Example\n\nHere is an example of a PHP Commando script that gives a decent tour of Commando's features. Let's say it is in a file called `hello.php`.\n\n```php\n\u003c?php\n\nrequire_once 'vendor/autoload.php';\n\n$hello_cmd = new Commando\\Command();\n\n// Define first option\n$hello_cmd-\u003eoption()\n    -\u003erequire()\n    -\u003edescribedAs('A person\\'s name');\n\n// Define a flag \"-t\" a.k.a. \"--title\"\n$hello_cmd-\u003eoption('t')\n    -\u003eaka('title')\n    -\u003edescribedAs('When set, use this title to address the person')\n    -\u003emust(function($title) {\n        $titles = array('Mister', 'Mr', 'Misses', 'Mrs', 'Miss', 'Ms');\n        return in_array($title, $titles);\n    })\n    -\u003emap(function($title) {\n        $titles = array('Mister' =\u003e 'Mr', 'Misses' =\u003e 'Mrs', 'Miss' =\u003e 'Ms');\n        if (array_key_exists($title, $titles))\n            $title = $titles[$title];\n        return \"$title. \";\n    });\n\n// Define a boolean flag \"-c\" aka \"--capitalize\"\n$hello_cmd-\u003eoption('c')\n    -\u003eaka('capitalize')\n    -\u003eaka('cap')\n    -\u003edescribedAs('Always capitalize the words in a name')\n    -\u003eboolean();\n\n// Define an incremental flag \"-e\" aka \"--educate\"\n$hello_cmd-\u003eoption('e')\n    -\u003eaka('educate')\n    -\u003emap(function($value) {\n        $postfix = array('', 'Jr', 'esq', 'PhD');\n        return $postfix[$value] === '' ? '' : \" {$postfix[$value]}\";\n    })\n    -\u003ecount(4);\n\n$name = $hello_cmd['capitalize'] ? ucwords($hello_cmd[0]) : $hello_cmd[0];\n\necho \"Hello {$hello_cmd['title']}$name{$hello_cmd['educate']}!\", PHP_EOL;\n```\n\nRunning it:\n\n    \u003e php hello.php Nate\n    Hello, Nate!\n\n    \u003e php hello.php --capitalize nate\n    Hello, Nate!\n\n    \u003e php hello.php -c -t Mr 'nate good'\n    Hello, Mr. Nate Good!\n\n    \u003e php hello.php -ceet Mr 'nate good'\n    Hello, Mr. Nate Good esq!\n\nThings to note:\n\n- Commando implements ArrayAccess so it acts much like an array when you want to retrieve values for it\n- For \"anonymous\" (i.e. not a named flag) arguments, we access them based on their numeric index\n- We can access option values in an array via a flags name OR its alias\n- We can use closures to perform validation and map operations right as part of our option definition\n\n## Baked in Help\n\nCommando has automatic `--help` support built in. Calling your script with this flag will print out a pretty help page based on your option definitions and Commando settings. If you define an option with the alias of 'help', it will override this built in support.\n\n![help screenshot](http://cl.ly/image/1y3i2m2h220u/Screen%20Shot%202012-08-19%20at%208.54.49%20PM.png)\n\n## Error Messaging\n\nBy default, Commando will catch Exceptions that occur during the parsing process. Instead, Commando prints a formatted, user-friendly error message to standard error and exits with a code of 1. If you wish to have Commando throw Exceptions in these cases, call the `doNotTrapErrors` method on your Command instance.\n\n![error screenshot](http://f.cl.ly/items/150H2d3x0l3O3J0s3i1G/Screen%20Shot%202012-08-19%20at%209.58.21%20PM.png)\n\n## Command Methods\n\nThese options work on the \"command\" level.\n\n### `useDefaultHelp (bool help)`\n\nThe default behavior of Commando is to provide a `--help` option that spits out a useful help page generated off of your option definitions. Disable this feature by calling `useDefaultHelp(false)`\n\n### `setHelp (string help)`\n\nText to prepend to the help page. Use this to describe the command at a high level and maybe some examples usages of the command.\n\n### `printHelp()`\n\nPrint the default help for the command. Useful if you want to output help if no arguments are passed.\n\n### `beepOnError (bool beep=true)`\n\nWhen an error occurs, print character to make the terminal \"beep\".\n\n### `getOptions`\n\nReturn an array of `Options` for each options provided to the command.\n\n### `getFlags`\n\nReturn an array of `Options` for only the flags provided to the command.\n\n### `getArguments`\n\nReturn an array of `Options` for only the arguments provided to the command. The order of the array is the same as the order of the arguments.\n\n### `getFlagValues`\n\nReturn associative array of values for arguments provided to the command. E.g. `array('f' =\u003e 'value1')`.\n\n### `getArgumentValues`\n\nReturn array of values for arguments provided to the command. E.g. `array('value1', 'value2')`.\n\n## Command Option Definition Methods\n\nThese options work on the \"option\" level, even though they are chained to a `Command` instance\n\n### `option (mixed $name = null)`\n\nAliases: `o`\n\nDefine a new option. When `name` is set, the option will be a named \"flag\" option. Can be a short form option (e.g. `f` for option `-f`) or long form (e.g. `foo` for option --foo). When no `name` is defined, the option is an anonymous argument and is referenced in the future by its position.\n\n### `flag (string $name)`\n\nSame as `option` except that it can only be used to define \"flag\" type options (a.k.a. those options that must be specified with a -flag on the command line).\n\n### `argument ()`\n\nSame as `option` except that it can only be used to define \"argument\" type options (a.k.a those options that are specified WITHOUT a -flag on the command line).\n\n### `alias (string $alias)`\n\nAliases: `a`, `aka`\n\nAdd an alias for a named option. This method can be called multiple times to add multiple aliases.\n\n### `description (string $description)`\n\nAliases: `d`, `describe`, `describedAs`\n\nText to describe this option. This text will be used to build the \"help\" page and as such, it is end user facing.\n\n### `require (bool $require)`\n\nAliases: `r`, `required`\n\nRequire that this flag is specified\n\n### `needs (string|array $options)`\n\nAliases: none\n\nRequire that other $options be set for this option to be used.\n\n### `must (Closure $rule)`\n\nAliases: _N/A_\n\nDefine a rule to validate input against. Takes function that accepts a string $value and returns a boolean as to whether or not $value is valid.\n\n### `map (Closure $map)`\n\nAliases: `cast`, `castTo`\n\nPerform a map operation on the value for this option. Takes function that accepts a string $value and return mixed (you can map to whatever you wish).\n\n### `reduce (Closure $reducer [, mixed $seed])`\n\nAliases: `list`, `each`, `every`\n\nExecute an accumulator/reducer function on every instance of the option in the command. Takes an accumulator function, and returns mixed (you can return any value). If you also supply a map for the option the map will execute on every value before it is passed to the accumulator function. If `$seed` value is supplied, this will be used as the default value.\n\nSignature: `function(mixed $accumulated, mixed $value) : mixed`\n\n- `$accumulated`: null|Option::default|mixed (the last value returned from the function, the option default value, or null.)\n- `$value`: mixed (the value that comes after the option. if map is supplied, the value returned from the map function.)\n- `return`: mixed (anything you want. The last value returned becomes the value of the Option after parsing.)\n\n### `referToAs (string $name)`\n\nAliases: `title`, `referredToAs`\n\nAdd a name to refer to an argument option by. Makes the help docs a little cleaner for anonymous \"argument\" options.\n\n### `boolean ()`\n\nAliases: _N/A_\n\nSpecifices that the flag is a boolean type flag.\n\n### `increment (int $max)`\n\nAliases: `i`, `count`, `repeats`, `repeatable`\n\nSpecifies that the flag is a counter type flag. The value of the flag will be incremented up to the value of `$max` for each time the flag is used in the command. Options that are set to `increment` or `boolean` types can be grouped together.\n\n### `default (mixed $defaultValue)`\n\nAliases: `defaultsTo`\n\nIf the value is not specified, default to `$defaultValue`.\n\nIn the case of `boolean()` type flags, when the flag is present, the value of this option the negation of `$defaultValue`. That is to say, if you have a flag -b with a default of `true`, when -b is present as a command line flag, the value of the option will be `false`.\n\n### `file ()`\n\nAliases: `expectsFile`\n\nThe value specified for this option must be a valid file path. When used relative paths will be converted into fully quantify file paths and globbing is also optionally supported. See the file.php example.\n\n### `boolean ()`\n\nAliases: _N/A_\n\nSpecifices that the flag is a boolean type flag.\n\n### `default (mixed $defaultValue)`\n\nAliases: `defaultsTo`\n\nIf the value is not specified, default to `$defaultValue`.\n\nIn the case of `boolean()` type flags, when the flag is present, the value of this option the negation of `$defaultValue`. That is to say, if you have a flag -b with a default of `true`, when -b is present as a command line flag, the value of the option will be `false`.\n\n### `file ()`\n\nAliases: `expectsFile`\n\nThe value specified for this option must be a valid file path. When used relative paths will be converted into fully quatified file paths and globbing is also optionally supported. See the file.php example.\n\n## Contributing\n\nCommando highly encourages sending in pull requests. When submitting a pull request please:\n\n- All pull requests should target the `dev` branch (not `master`)\n- Make sure your code follows the coding standards laid out in [PSR-1](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md) and [PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)\n- Make sure you add appropriate test coverage for your changes\n- Run all unit tests in the test directory via `phpunit ./tests`\n- Include commenting where appropriate and add a descriptive pull request message\n\n## Inspiration\n\n- [Commander](https://github.com/visionmedia/commander/)\n- [Optimist](https://github.com/substack/node-optimist)\n\nReleased under MIT license.\n\n## Change Log\n\n### v1.0.1\n\n- Add support for negative numbers not to be misinterpreted as bad options.\n\n### v1.0.0\n\n- Dropping support for anything before PHP 8.1\n\n### v0.4.0\n\n- Dropping support for 5.4 and 5.5, bumping minor version number\n- [PR #93](https://github.com/nategood/commando/pull/93) FEATURE Add `reducer` option\n- [PR #95](https://github.com/nategood/commando/pull/95) FIX Remove tput call on Windows OS\n- [PR #101](https://github.com/nategood/commando/pull/101) FIX Only evaluate 'needs' constraints of an option if that option is actually used\n- [PR #76](https://github.com/nategood/commando/pull/76/) FIX Fix non-empty getArgumentValues array when using anonymous args\n\n### v0.3.0\n\n- Dropped PHP 5.3\n\n### v0.2.9\n\n- PR #63 FEATURE incremental flags\n- PR #60 MINOR getDescription method\n\n### v0.2.8\n\n- Bug fix for #34\n\n### v0.2.7\n\n- `getOptions` added (along with some better documentation)\n\n### v0.2.6\n\n- Adds support for \"needs\" to define dependencies between options (thanks @enygma) [PR #31](https://github.com/nategood/commando/pull/31)\n- Fixes issue with long-argument-names [Issue #30](https://github.com/nategood/commando/issues/30)\n\n### v0.2.5\n\n- Fixed up default values for boolean options, automatically default boolean options to false (unlikely, but potentially breaking change) [PR #19](https://github.com/nategood/commando/pull/19)\n\n### v0.2.4\n\n- Added ability to define default values for options\n\n### v0.2.3\n\n- Improved Help Formatting [PR #12](https://github.com/nategood/commando/pull/12)\n\n### v0.2.2\n\n- Bug fix for printing double help [PR #10](https://github.com/nategood/commando/pull/10)\n\n### v0.2.1\n\n- Adds support for requiring options to be valid file paths or globs\n- Returns a fully qualified file path name (e.g. converts relative paths)\n- Returns an array of file paths in the case of globbing\n- See the file.php example in the examples directory\n\n### v0.2.0\n\nThe primary goal of this update was to better delineate between flag options and argument options. In Commando, flags are options that we define that require a name when they are being specified on the command line. Arguments are options that are not named in this way. In the example below, '-f' and '--long' are described as \"flags\" type options in Commando terms with the values 'value1' and 'value2' respectively, whereas value3, value4, and value5 are described as \"argument\" type options.\n\n```\nphp command.php -f value1 --long value2 value3 value4 value5\n```\n\n- Added Command::getArguments() to return an array of `Option` that are of the \"argument\" type (see argumentsVsFlags.php example)\n- Added Command::getFlags() to return an array of `Option` that are of the \"flag\" type (see argumentsVsFlags.php example)\n- Added Command::getArgumentValues() to return an array of all the values for \"arguments\"\n- Added Command::getFlagValues() to return an array of all values for \"flags\"\n- Command now implements Iterator interface and will iterator over all options, starting with arguments and continuing with flags in alphabetical order\n- Can now define options with Command::flag($name) and Command::argument(), in addition to Command::option($name)\n- Added ability to add a \"title\" to refer to arguments by, making the help docs a little cleaner (run help.php example)\n- Cleaned up the generated help docs\n- Bug fix for additional colorized red line when an error is displayed\n\n### v0.1.4\n\n- Bug fix for options values with multiple words\n\n### v0.1.3\n\n- Beep support added to Terminal\n- Commando::beepOnError() added\n\n### v0.1.2\n\n- Terminal updated to use tput correctly\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnategood%2Fcommando","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnategood%2Fcommando","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnategood%2Fcommando/lists"}