{"id":16824793,"url":"https://github.com/tomnomnom/phargs","last_synced_at":"2025-03-22T03:31:48.634Z","repository":{"id":5846285,"uuid":"7062775","full_name":"tomnomnom/phargs","owner":"tomnomnom","description":"A toolkit for writing CLI scripts in PHP","archived":false,"fork":false,"pushed_at":"2016-03-28T16:44:01.000Z","size":99,"stargazers_count":26,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-18T07:51:34.763Z","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/tomnomnom.png","metadata":{"files":{"readme":"README.mkd","changelog":"CHANGELOG.mkd","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-12-08T01:38:38.000Z","updated_at":"2025-02-18T20:02:27.000Z","dependencies_parsed_at":"2022-08-31T17:11:36.759Z","dependency_job_id":null,"html_url":"https://github.com/tomnomnom/phargs","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomnomnom%2Fphargs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomnomnom%2Fphargs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomnomnom%2Fphargs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tomnomnom%2Fphargs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tomnomnom","download_url":"https://codeload.github.com/tomnomnom/phargs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244902929,"owners_count":20529114,"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-10-13T11:12:02.169Z","updated_at":"2025-03-22T03:31:48.158Z","avatar_url":"https://github.com/tomnomnom.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Phargs\n\nPhargs is a toolkit for writing CLI scripts in PHP; it was born out of frustration, anger, and \nboilerplate déjà vu. Pull requests, issues, and suggestions are always welcome.\n\nPhargs' main asset is its argument processor, but the output tools are pretty useful too.\n\nEverything in Phargs is available through `\\Phargs\\Factory`.\n\n## Contents\nThis README file is a little long, so here's a breakdown of the contents:\n\n* [Installation](#installation)\n* [Argument processing](#argument-processing)\n  - [Flags - Intro](#flags)\n  - [Flags - Basic usage](#basic-usage)\n  - [Flags - Flag aliases](#flag-aliases)\n  - [Flags - Compound flags](#compound-flags)\n  - [Params - Intro](#params)\n  - [Params - Basic usage](#basic-usage-1)\n  - [Params - Param aliases](#param-aliases)\n  - [Params - Required params](#required-params)\n  - [Residual args](#residual-args)\n* [Outputting to the screen](#outputting-to-the-screen)\n  - [Basic usage](#basic-usage-2)\n  - [Colors](#colors)\n* [Prompting for input](#prompting-for-input)\n  - [Basic usage](#basic-usage-3)\n  - [Required input](#required-input)\n* [Formatting](#formatting)\n  - [Tables](#tables)\n  - [TSV](#tsv)\n* [Requirements](#requirements)\n* [Testing](#testing)\n\n## Installation \n\nPhargs is available on [Packagist](https://packagist.org/packages/tomnomnom/phargs) so you can \ninstall it using [Composer](http://getcomposer.org/). Just specify it as a dependency in your \n`composer.json`:\n\n```json\n{\n    \"require\": {\n        \"tomnomnom/phargs\": \"0.0.5\"\n    }\n}\n```\n\nThen run `composer install`:\n\n    ▶ composer install\n    Loading composer repositories with package information\n    Installing dependencies\n      - Installing tomnomnom/phargs (0.0.2)\n        Loading from cache\n    \n    Writing lock file\n    Generating autoload files\n\n\nOnce installed you can use the composer autoloader instead of the `Phargs/Init.php` script that \nthe included examples use:\n\n```php\n\u003c?php\nrequire __DIR__.'/vendor/autoload.php';\n\n$factory = new \\Phargs\\Factory();\n$screen = $factory-\u003escreen();\n\n$screen-\u003eoutln(\"Hello, World!\");\n```\n\n\n## Argument processing\nThe [getopt](http://php.net/manual/en/function.getopt.php) interface isn't the most friendly thing in the world,\nPhargs tries to make your life a bit easier.\n \nThe argument processor is available via `\\Phargs\\Factory::args()`.\n\n### Flags\nA *flag* is an argument that turns functionality on or off. Common examples are `-h` to display \na help message or `--verbose` to display more output. \n\n#### Basic usage\nPhargs needs to be told to *expect* a flag in order to use it.\n\n```php\n\u003c?php\n// ./Examples/Flags.php\n\n// Bootstrap Phargs\ninclude __DIR__.'/../Phargs/Init.php';\n\n// Everything in Phargs is available via the Factory\n$factory = new \\Phargs\\Factory();\n\n// Get an argument processor\n$args = $factory-\u003eargs();\n\n// Expect the -h flag to be an argument\n$args-\u003eexpectFlag('-h');\n\nif ($args-\u003eflagIsSet('-h')){\n  echo \"Help flag is set\\n\";\n} else {\n  echo \"Help flag is not set\";\n}\n```\n    ▶ php ./Examples/Flags.php -h\n    Help flag is set\n    ▶ php ./Examples/Flags.php\n    Help flag is not set\n\n#### Flag aliases\nYou can *alias* flags to make your script more user friendly. Phargs supports both \nlong (e.g. `--help`) and short (e.g. `-h`) flags.\n\n```php\n\u003c?php\n// ./Examples/FlagAliases.php\n\ninclude __DIR__.'/../Phargs/Init.php';\n$factory = new \\Phargs\\Factory();\n$args = $factory-\u003eargs();\n\n$args-\u003eexpectFlag('-h');\n\n// Alias the -h flag to --help so either can be used\n$args-\u003eaddFlagAlias('-h', '--help');\n\n// You could check for --help instead of -h here and it would still work\nif ($args-\u003eflagIsSet('-h')){\n  echo \"Help flag is set\\n\";\n} else {\n  echo \"Help flag is not set\\n\";\n}\n```\n    ▶ php ./Examples/FlagAliases.php -h\n    Help flag is set\n    ▶ php ./Examples/FlagAliases.php --help\n    Help flag is set\n\n#### Compound flags\nPhargs also supports *compound flags*; like how you might run `grep -Hnr $searchString *`.\n\n```php\n\u003c?php\n// ./Examples/CompoundFlags.php\n\ninclude __DIR__.'/../Phargs/Init.php';\n$factory = new \\Phargs\\Factory();\n$args = $factory-\u003eargs();\n\n$args-\u003eexpectFlag('-H');\n$args-\u003eexpectFlag('-n');\n$args-\u003eexpectFlag('-r');\n\nif ($args-\u003eflagIsSet('-H')){\n  echo \"-H flag is set\\n\";\n}\nif ($args-\u003eflagIsSet('-n')){\n  echo \"-n flag is set\\n\";\n}\nif ($args-\u003eflagIsSet('-r')){\n  echo \"-r flag is set\\n\";\n}\n```\n\n    ▶ php ./Examples/CompoundFlags.php -Hnr\n    -H flag is set\n    -n flag is set\n    -r flag is set\n    ▶ php ./Examples/CompoundFlags.php -H -nr\n    -H flag is set\n    -n flag is set\n    -r flag is set\n    ▶ php ./Examples/CompoundFlags.php -Hni # Note: 'i' is unexpected\n    -H flag is set\n    -n flag is set\n    ▶ php ./Examples/CompoundFlags.php -n -r\n    -n flag is set\n    -r flag is set\n\n### Params\nA *param* is an argument that provides a value. They come in 4 flavours:\n\n* Long, with an equals (e.g. `--count=5`)\n* Long, with a space (e.g. `--count 5`)\n* Short, with a space (e.g. `-c 5`)\n* Short, without a space (e.g. `-c5`)\n\n#### Basic usage\nLike with flags, you must tell Phargs to *expect* a param. Unlike flags, you can also get the \n*value* of a param:\n\n```php\n\u003c?php\n// ./Examples/Params.php\n\n// Bootstrap Phargs\ninclude __DIR__.'/../Phargs/Init.php';\n\n// Everything in Phargs is available via the Factory\n$factory = new \\Phargs\\Factory();\n\n// Get an argument processor\n$args = $factory-\u003eargs();\n\n// Expect the --count param\n$args-\u003eexpectParam('--count');\n\nif ($args-\u003eparamIsSet('--count')){\n  echo \"--count param is set\\n\";\n  echo \"--count value is: \";\n  echo $args-\u003egetParamValue('--count').PHP_EOL;\n} else {\n  echo \"--count param is not set\\n\";\n}\n```\n    ▶ php ./Examples/Params.php --count=5\n    --count param is set\n    --count value is: 5\n    ▶ php ./Examples/Params.php --count 5\n    --count param is set\n    --count value is: 5\n    ▶ php ./Examples/Params.php --help\n    --count param is not set\n\n#### Param aliases\nLike flags, params can be aliased:\n\n```php\n\u003c?php\n// ./Examples/ParamAliases.php\n\ninclude __DIR__.'/../Phargs/Init.php';\n$factory = new \\Phargs\\Factory();\n$args = $factory-\u003eargs();\n\n// Expect the --count param\n$args-\u003eexpectParam('--count');\n\n// Alias --count to -c so that either can be used\n$args-\u003eaddParamAlias('--count', '-c');\n\nif ($args-\u003eparamIsSet('--count')){\n  echo \"--count param is set\\n\";\n  echo \"--count value is: \";\n  echo $args-\u003egetParamValue('-c').PHP_EOL;\n} else {\n  echo \"--count param is not set\\n\";\n}\n```\n\n    ▶ php ./Examples/ParamAliases.php --count=5\n    --count param is set\n    --count value is: 5\n    ▶ php ./Examples/ParamAliases.php -c 5\n    --count param is set\n    --count value is: 5\n    ▶ php ./Examples/ParamAliases.php -c5\n    --count param is set\n    --count value is: 5\n    \n#### Required params\nIn the examples so far Phargs has *expected* to see params, but it doesn't mind if they're not there. \nIf a param is important enough you can *require* that it exists and then check that all requirements are met:\n\n```php\n\u003c?php\n// ./Examples/RequiredParams.php\n\ninclude __DIR__.'/../Phargs/Init.php';\n$factory = new \\Phargs\\Factory();\n$args = $factory-\u003eargs();\n\n// Require some params\n$args-\u003erequireParam('--count');\n$args-\u003erequireParam('--number');\n\n// Check that all argument requirements are met\nif ($args-\u003erequirementsAreMet()){\n  echo \"All arg requirements are met\\n\";\n} else {\n  echo \"Not all arg requirements are met\\n\";\n}\n```\n\n    ▶ php ./Examples/RequiredParams.php --count=4 --number=5\n    All arg requirements are met\n    ▶ php ./Examples/RequiredParams.php --count=4 \n    Not all arg requirements are met\n\n### Residual args\n*Residual args* are the arguments left over when expected params and flags have been removed. For example:\n\n    ./command -v help merge\n    \nAssuming the `-v` flag is expected by Phargs: `help` and `merge` are considered to be residual args. Residual\nargs are zero-indexed, and their indexes remain the same regardless of where any expected flags or params\nappear in the argument list. \n\nYou can get one, all, or a range of residual args:\n\n```php\n\u003c?php\n// ./Examples/ResidualArgs.php\n\ninclude __DIR__.'/../Phargs/Init.php';\n$factory = new \\Phargs\\Factory();\n$args = $factory-\u003eargs();\n\n// We're expecting some arguments\n$args-\u003eexpectParam('--count');\n$args-\u003eexpectFlag('-h');\n\n// Arguments we're not expecting are considered 'residual'\necho \"Residual arg #0: \".$args-\u003egetResidualArg(0).PHP_EOL;\necho \"All residual args: \".implode(', ', $args-\u003egetResidualArgs()).PHP_EOL;\necho \"First two residual args: \".implode(', ', $args-\u003egetResidualArgs(0, 2)).PHP_EOL;\n```\n\n    ▶ php ./Examples/ResidualArgs.php -h help merge\n    Residual arg #0: help\n    All residual args: help, merge\n    First two residual args: help, merge\n    ▶ php ./Examples/ResidualArgs.php help -h merge\n    Residual arg #0: help\n    All residual args: help, merge\n    First two residual args: help, merge\n    ▶ php ./Examples/ResidualArgs.php help -h merge this thing\n    Residual arg #0: help\n    All residual args: help, merge, this, thing\n    First two residual args: help, merge\n\n\n## Outputting to the screen\nPhargs provides an interface for outputting text to the screen.\n\nThe screen interface is available via `\\Phargs\\Factory::screen()`.\n\n### Basic usage\nAmongst other things, the screen interface provides methods to write to `stdout` and `stderr`, with or \nwithout trailing newline characters. It also provides some methods that are useful when debugging.\n\n```php\n\u003c?php\n// ./Examples/ScreenBasic.php\n\ninclude __DIR__.'/../Phargs/Init.php';\n$factory = new \\Phargs\\Factory();\n\n// Get a screen interface\n$screen = $factory-\u003escreen();\n\n$screen-\u003eout(\"Hello, \");\n$screen-\u003eoutln(\"World!\");\n\n$screen-\u003eerr(\"Error \");\n$screen-\u003eerrln(\"message\");\n\n$screen-\u003eprintf(\"When in %s\".PHP_EOL, \"Rome\");\n\n$testVar = array(1, 2, 3);\n$screen-\u003evarExport($testVar);\n\n$screen-\u003elog('A log message');\n```\n\n    ▶ php ./Examples/ScreenBasic.php \n    Hello, World!\n    Error message\n    When in Rome\n    array (\n      0 =\u003e 1,\n      1 =\u003e 2,\n      2 =\u003e 3,\n    )\n    2012-12-22T15:16:50+00:00: A log message\n\n### Colors\nAlthough difficult to demonstrate in a README file, Phargs supports ANSI colors.\n\n```php\n\u003c?php\n// ./Examples/ScreenColors.php\n\ninclude __DIR__.'/../Phargs/Init.php';\n$factory = new \\Phargs\\Factory();\n\n// Get a screen interface\n$screen = $factory-\u003escreen();\n\n$screen-\u003eoutln(\"Red\", 'red');\n$screen-\u003eoutln(\"Red with a white background\", \"red\", \"white\");\n$screen-\u003eoutln(\"Red with a white background, underlined\", \"red\", \"white\", \"underline\");\n```\n\n    ▶ php ./Examples/ScreenColors.php \n    Red\n    Red with a white background\n    Red with a white background, underlined\n    \nThey really are in color; honest!\n\n8 colors are supported:\n* `black`\n* `red`\n* `green`\n* `yellow`\n* `blue`\n* `purple`\n* `cyan`\n* `white`\n\n3 different *styles* are supported:\n* `regular`\n* `bold`\n* `underline`\n\n## Prompting for input\nPhargs has an interface for prompting for user input. \n\nThe prompter is available via `\\Phargs\\Factory::prompter()`.\n\n### Basic usage\nThe `prompt` method can be used to *prompt* the user for some input. The trailing newline character is removed.\n\n```php\n\u003c?php\n// ./Examples/PrompterBasic.php\n\ninclude __DIR__.'/../Phargs/Init.php';\n$factory = new \\Phargs\\Factory();\n$screen = $factory-\u003escreen();\n\n// Get a prompter\n$prompter = $factory-\u003eprompter();\n\n// Prompt for some input\n$name = $prompter-\u003eprompt('What is your name? ');\n\n// Do something with the response\n$screen-\u003eoutln(\"Hello, {$name}!\");\n```\n\n    ▶ php ./Examples/PrompterBasic.php \n    What is your name? Tom\n    Hello, Tom!\n\n### Required input \nYou can also require that a user input some information, optionally displaying a message when they don't. \n\n```php\n\u003c?php\n// ./Examples/PrompterRequired.php\n\ninclude __DIR__.'/../Phargs/Init.php';\n$factory = new \\Phargs\\Factory();\n$screen = $factory-\u003escreen();\n\n// Get a prompter\n$prompter = $factory-\u003eprompter();\n\n// Prompt for some required input\n$name = $prompter-\u003epromptRequired('What is your name? ', 'No name entered!');\n\n// Do something with the response\n$screen-\u003eoutln(\"Hello, {$name}!\");\n```\n\n    ▶ php ./Examples/PrompterRequired.php \n    What is your name? \n    No name entered!\n    What is your name? Tom\n    Hello, Tom!\n\n## Formatting\n\n\n### Tables\nThe table formatter works out how wide to make each column so that everything lines up. It's available via `\\Phargs\\Factory::table()`.\n\n```php\n\u003c?php\n// ./Examples/Table.php\n\ninclude __DIR__.'/../Phargs/Init.php';\n$factory = new \\Phargs\\Factory();\n$screen = $factory-\u003escreen();\n\n// Get a table formatter\n$table = $factory-\u003etable();\n\n$table-\u003esetFields(array('id', 'name'));\n$table-\u003eaddRows(array(\n  array(1, 'Tom'),\n  array(2, 'Dick'),\n  array(3, 'Harry'),\n));\n\n$screen-\u003eout($table);\n```\n\n    ▶ php ./Examples/Table.php\n    --------------\n    | id | name  |\n    --------------\n    | 1  | Tom   |\n    | 2  | Dick  |\n    | 3  | Harry |\n    --------------\n\n### TSV\nThe TSV (Tab Separated Values) formatter is very similar to the Table formatter. It's available via `\\Phargs\\Factory::tsv()`.\n\n```php\n\u003c?php\n// ./Examples/Tsv.php\n\ninclude __DIR__.'/../Phargs/Init.php';\n$factory = new \\Phargs\\Factory();\n$screen = $factory-\u003escreen();\n\n// Get a TSV formatter\n$table = $factory-\u003etsv();\n\n$table-\u003esetFields(array('id', 'name'));\n$table-\u003eaddRows(array(\n  array(1, 'Tom'),\n  array(2, 'Dick'),\n  array(3, 'Harry'),\n));\n\n$screen-\u003eout($table);\n```\n\n    ▶ php ./Examples/Tsv.php\n    id      name\n    1       Tom\n    2       Dick\n    3       Harry\n\n## Requirements\n\n* Linux of some description\n* PHP 5.3 or newer\n\n## Testing\n\nYou can run the full test suite by running:\n\n    ▶ phpunit\n\nThe tests are actually split up into 3 suites, which can be run individually:\n\n    ▶ phpunit --filter Unit\n    ▶ phpunit --filter Integration\n    ▶ phpunit --filter FullStack\n\nThe repo is hooked up to Travis CI. You can see the state of the master branch and the \nbuild history on the [Phargs Travis CI page](https://travis-ci.org/tomnomnom/phargs).\nThe full test suite runs under PHP 5.3 and PHP 5.4.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomnomnom%2Fphargs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomnomnom%2Fphargs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomnomnom%2Fphargs/lists"}