{"id":13616483,"url":"https://github.com/php-toolkit/pflag","last_synced_at":"2025-08-20T08:17:16.745Z","repository":{"id":43041675,"uuid":"399397604","full_name":"php-toolkit/pflag","owner":"php-toolkit","description":"Generic PHP command line flags parse library. ","archived":false,"fork":false,"pushed_at":"2025-08-12T11:18:27.000Z","size":515,"stargazers_count":34,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-12T13:29:45.139Z","etag":null,"topics":["cli","cli-application","cli-arguments","cli-flags","cli-options","cli-parser","command-line","command-line-app","flag-parser","flags"],"latest_commit_sha":null,"homepage":"https://php-toolkit.github.io/pflag/","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/php-toolkit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2021-08-24T08:53:14.000Z","updated_at":"2025-08-12T11:18:24.000Z","dependencies_parsed_at":"2024-01-18T12:52:20.295Z","dependency_job_id":"c54a230d-7c9b-4cef-9b07-febd84257f78","html_url":"https://github.com/php-toolkit/pflag","commit_stats":{"total_commits":108,"total_committers":3,"mean_commits":36.0,"dds":0.02777777777777779,"last_synced_commit":"6619dc82da0bd9a1253fb53af4338759fe170ae8"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":"inherelab/php-pkg-template","purl":"pkg:github/php-toolkit/pflag","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-toolkit%2Fpflag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-toolkit%2Fpflag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-toolkit%2Fpflag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-toolkit%2Fpflag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/php-toolkit","download_url":"https://codeload.github.com/php-toolkit/pflag/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/php-toolkit%2Fpflag/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271285534,"owners_count":24732930,"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","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cli","cli-application","cli-arguments","cli-flags","cli-options","cli-parser","command-line","command-line-app","flag-parser","flags"],"created_at":"2024-08-01T20:01:29.156Z","updated_at":"2025-08-20T08:17:16.726Z","avatar_url":"https://github.com/php-toolkit.png","language":"PHP","readme":"# PHP Flag\n\n[![License](https://img.shields.io/packagist/l/toolkit/pflag.svg?style=flat-square)](LICENSE)\n[![GitHub tag (latest SemVer)](https://img.shields.io/github/tag/php-toolkit/pflag)](https://github.com/php-toolkit/pflag)\n[![Actions Status](https://github.com/php-toolkit/pflag/workflows/Unit-Tests/badge.svg)](https://github.com/php-toolkit/pflag/actions)\n[![Php Version Support](https://img.shields.io/packagist/php-v/toolkit/pflag)](https://packagist.org/packages/toolkit/pflag)\n[![Latest Stable Version](http://img.shields.io/packagist/v/toolkit/pflag.svg)](https://packagist.org/packages/toolkit/pflag)\n[![Coverage Status](https://coveralls.io/repos/github/php-toolkit/pflag/badge.svg?branch=main)](https://coveralls.io/github/php-toolkit/pflag?branch=main)\n[![zh-CN readme](https://img.shields.io/badge/中文-Readme-brightgreen.svg?style=for-the-badge\u0026maxAge=2592000)](README.zh-CN.md)\n\nGeneric PHP command line flags parse library\n\n\u003e Github: [php-toolkit/pflag](https://github.com/php-toolkit/pflag)\n\n## Features\n\n- Generic command line options and arguments parser.\n- Support set value data type(`int,string,bool,array`), will auto format input value.\n- Support set multi alias names for an option.\n- Support set multi short names for an option.\n- Support set default value for option/argument.\n- Support read flag value from ENV var.\n- Support set option/argument is required.\n- Support set validator for check input value.\n- Support auto render beautiful help message.\n\n**Flag Options**:\n\n- Options start with `-` or `--`, and the first character must be a letter\n- Support long option. eg: `--long` `--long value`\n- Support short option. eg: `-s -a value`\n- Support define array option\n  - eg: `--tag php --tag go` will get `tag: [php, go]`\n\n**Flag Arguments**:\n\n- Support binding named arguemnt\n- Support define array argument\n\n### Quick build command\n\n- Use `Toolkit\\PFlag\\CliCmd` to quickly build a simple command application\n- Use `Toolkit\\PFlag\\CliApp` to quickly build a command application that supports subcommands\n\n## Install\n\n- Require PHP 8.0+\n\n**composer**\n\n```bash\ncomposer require toolkit/pflag\n```\n\n-----------\n\n## Flags Usage\n\nFlags - is an cli flags(options\u0026argument) parser and manager.\n\n\u003e example codes please see [example/flags-demo.php](example/flags-demo.php)\n\n### Create Flags\n\n```php\nuse Toolkit\\PFlag\\Flags;\n\nrequire dirname(__DIR__) . '/test/bootstrap.php';\n\n$flags = $_SERVER['argv'];\n// NOTICE: must shift first element.\n$scriptFile = array_shift($flags);\n\n$fs = Flags::new();\n// can with some config\n$fs-\u003esetScriptFile($scriptFile);\n/** @see Flags::$settings */\n$fs-\u003esetSettings([\n    'descNlOnOptLen' =\u003e 26\n]);\n\n// ...\n```\n\n### Define options\n\nExamples for add flag option define:\n\n```php\nuse Toolkit\\PFlag\\Flag\\Option;\nuse Toolkit\\PFlag\\FlagType;\nuse Toolkit\\PFlag\\Validator\\EnumValidator;\n\n// add options\n// - quick add\n$fs-\u003eaddOpt('age', 'a', 'this is a int option', FlagType::INT);\n\n// - use string rule\n$fs-\u003eaddOptByRule('name,n', 'string;this is a string option;true');\n\n// - use array rule\n/** @see Flags::DEFINE_ITEM for array rule */\n$fs-\u003eaddOptByRule('name-is-very-lang', [\n    'type'   =\u003e FlagType::STRING,\n    'desc'   =\u003e 'option name is to lang, desc will print on newline',\n    'shorts' =\u003e ['d','e','f'],\n    // TIP: add validator limit input value.\n    'validator' =\u003e EnumValidator::new(['one', 'two', 'three']),\n]);\n\n// -- add multi option at once.\n$fs-\u003eaddOptsByRules([\n    'tag,t' =\u003e 'strings;array option, allow set multi times',\n    'f'     =\u003e 'bool;this is an bool option',\n]);\n\n// - use Option\n$opt = Option::new('str1', \"this is  string option, \\ndesc has multi line, \\nhaha...\");\n$opt-\u003esetDefault('defVal');\n$fs-\u003eaddOption($opt);\n```\n\n### Define Arguments\n\nExamples for add flag argument define:\n\n```php\nuse Toolkit\\PFlag\\Flag\\Argument;\nuse Toolkit\\PFlag\\FlagType;\n\n// add arguments\n// - quick add\n$fs-\u003eaddArg('strArg1', 'the is string arg and is required', 'string', true);\n\n// - use string rule\n$fs-\u003eaddArgByRule('intArg2', 'int;this is a int arg and with default value;no;89');\n\n// - use Argument object\n$arg = Argument::new('arrArg');\n// OR $arg-\u003esetType(FlagType::ARRAY);\n$arg-\u003esetType(FlagType::STRINGS);\n$arg-\u003esetDesc(\"this is an array arg,\\n allow multi value,\\n must define at last\");\n\n$fs-\u003eaddArgument($arg);\n```\n\n### Parse Input\n\n```php\nuse Toolkit\\PFlag\\Flags;\nuse Toolkit\\PFlag\\FlagType;\n\n// ...\n\nif (!$fs-\u003eparse($flags)) {\n    // on render help\n    return;\n}\n\nvdump($fs-\u003egetOpts(), $fs-\u003egetArgs());\n```\n\n**Show help**\n\n```bash\n$ php example/flags-demo.php --help\n```\n\nOutput:\n\n![flags-demo](example/images/flags-demo.png)\n\n**Run demo:**\n\n```bash\n$ php example/flags-demo.php --name inhere --age 99 --tag go -t php -t java -d one -f arg0 80 arr0 arr1\n```\n\nOutput:\n\n```text\n# options\narray(6) {\n  [\"str1\"]=\u003e string(6) \"defVal\"\n  [\"name\"]=\u003e string(6) \"inhere\"\n  [\"age\"]=\u003e int(99)\n  [\"tag\"]=\u003e array(3) {\n    [0]=\u003e string(2) \"go\"\n    [1]=\u003e string(3) \"php\"\n    [2]=\u003e string(4) \"java\"\n  }\n  [\"name-is-very-lang\"]=\u003e string(3) \"one\"\n  [\"f\"]=\u003e bool(true)\n}\n\n# arguments\narray(3) {\n  [0]=\u003e string(4) \"arg0\"\n  [1]=\u003e int(80)\n  [2]=\u003e array(2) {\n    [0]=\u003e string(4) \"arr0\"\n    [1]=\u003e string(4) \"arr1\"\n  }\n}\n```\n\n-----------\n\n## Get Value\n\nGet flag value is very simple, use method `getOpt(string $name)` `getArg($nameOrIndex)`.\n\n\u003e TIP: Will auto format input value by define type.\n\n**Options**\n\n```php\n$force = $fs-\u003egetOpt('f'); // bool(true)\n$age  = $fs-\u003egetOpt('age'); // int(99)\n$name = $fs-\u003egetOpt('name'); // string(inhere)\n$tags = $fs-\u003egetOpt('tags'); // array{\"php\", \"go\", \"java\"}\n```\n\n**Arguments**\n\n```php\n$arg0 = $fs-\u003egetArg(0); // string(arg0)\n// get an array arg\n$arrArg = $fs-\u003egetArg(1); // array{\"arr0\", \"arr1\"}\n// get value by name\n$arrArg = $fs-\u003egetArg('arrArg'); // array{\"arr0\", \"arr1\"}\n```\n\n-----------\n\n## Build simple cli app\n\nIn the pflag, built in `CliApp` and `CliCmd` for quick create and run an simple console application.\n\n### Create simple alone command\n\nBuild and run a simple command handler. see example file [example/clicmd.php](example/clicmd.php)\n\n```php\nuse Toolkit\\Cli\\Cli;\nuse Toolkit\\PFlag\\CliCmd;\nuse Toolkit\\PFlag\\FlagsParser;\n\nCliCmd::new()\n    -\u003econfig(function (CliCmd $cmd) {\n        $cmd-\u003ename = 'demo';\n        $cmd-\u003edesc = 'description for demo command';\n\n        // config flags\n        $cmd-\u003eoptions = [\n            'age, a'  =\u003e 'int;the option age, is int',\n            'name, n' =\u003e 'the option name, is string and required;true',\n            'tags, t' =\u003e 'array;the option tags, is array',\n        ];\n        // or use property\n        // $cmd-\u003earguments = [...];\n    })\n    -\u003ewithArguments([\n        'arg1' =\u003e 'this is arg1, is string'\n    ])\n    -\u003esetHandler(function (FlagsParser $fs) {\n        Cli::info('options:');\n        vdump($fs-\u003egetOpts());\n        Cli::info('arguments:');\n        vdump($fs-\u003egetArgs());\n    })\n    -\u003erun();\n```\n\n**Usage:**\n\n```php\n# show help\nphp example/clicmd.php -h\n# run command\nphp example/clicmd.php --age 23 --name inhere value1\n```\n\n- Display help:\n\n![cmd-demo-help](example/images/cli-cmd-help.png)\n\n- Run command:\n\n![cmd-demo-run](example/images/cli-cmd-run.png)\n\n### Create an multi commands app\n\nCreate an multi commands application, run subcommand. see example file [example/cliapp.php](example/cliapp.php)\n\n```php\nuse Toolkit\\Cli\\Cli;\nuse Toolkit\\PFlag\\CliApp;\nuse Toolkit\\PFlag\\FlagsParser;\nuse Toolkit\\PFlagTest\\Cases\\DemoCmdHandler;\n\n$app = new CliApp();\n\n$app-\u003eadd('test1', fn(FlagsParser $fs) =\u003e vdump($fs-\u003egetOpts()), [\n    'desc'    =\u003e 'the test 1 command',\n    'options' =\u003e [\n        'opt1' =\u003e 'opt1 for command test1',\n        'opt2' =\u003e 'int;opt2 for command test1',\n    ],\n]);\n\n$app-\u003eadd('test2', function (FlagsParser $fs) {\n    Cli::info('options:');\n    vdump($fs-\u003egetOpts());\n    Cli::info('arguments:');\n    vdump($fs-\u003egetArgs());\n}, [\n    // 'desc'    =\u003e 'the test2 command',\n    'options' =\u003e [\n        'opt1' =\u003e 'a string opt1 for command test2',\n        'opt2' =\u003e 'int;a int opt2 for command test2',\n    ],\n    'arguments' =\u003e [\n        'arg1' =\u003e 'required arg1 for command test2;true',\n    ]\n]);\n\n// fn - required php 7.4+\n$app-\u003eadd('show-err', fn() =\u003e throw new RuntimeException('test show exception'));\n\n$app-\u003eaddHandler(DemoCmdHandler::class);\n\n$app-\u003erun();\n```\n\n**Usage:**\n\n```php\n# show help\nphp example/cliapp.php -h\n# run command\nphp example/cliapp.php test2 --opt1 val1 --opt2 23 value1\n```\n\n- Display commands:\n\n![cli-app-help](example/images/cli-app-help.png)\n\n- Command help:\n\n![cli-app-cmd-help](example/images/cli-app-cmd-help.png)\n\n- Run command:\n\n![cli-app-cmd-run](example/images/cli-app-cmd-run.png)\n\n-----------\n\n## Flag rule\n\nThe options/arguments rules. Use rule can quick define an option or argument.\n\n- string value is rule(`type;desc;required;default;shorts`).\n- array is define item `SFlags::DEFINE_ITEM`\n- supported type see `FlagType::*`\n\n```php\nuse Toolkit\\PFlag\\FlagType;\n\n$rules = [\n     // v: only value, as name and use default type FlagType::STRING\n     // k-v: key is name, value can be string|array\n     'long,s',\n     // name =\u003e rule\n     'long,a,b' =\u003e 'int', // long is option name, a and b is shorts.\n     'f'      =\u003e FlagType::BOOL,\n     'str1'   =\u003e ['type' =\u003e 'int', 'desc' =\u003e 'an string option'],\n     'tags'   =\u003e 'array', // can also: ints, strings\n     'name'   =\u003e 'type;the description message;required;default', // with desc, default, required\n]\n```\n\n**For options**\n\n- option allow set shorts\n\n\u003e TIP: name `long,a,b` - `long` is the option name. remaining `a,b` is short names.\n\n**For arguments**\n\n- argument no alias/shorts\n- array value only allow defined at last\n\n**Definition item**\n\nThe const `Flags::DEFINE_ITEM`:\n\n```php\npublic const DEFINE_ITEM = [\n    'name'      =\u003e '',\n    'desc'      =\u003e '',\n    'type'      =\u003e FlagType::STRING,\n    'helpType'  =\u003e '', // use for render help\n    // 'index'    =\u003e 0, // only for argument\n    'required'  =\u003e false,\n    'default'   =\u003e null,\n    'shorts'    =\u003e [], // only for option\n    // value validator\n    'validator' =\u003e null,\n    // 'category' =\u003e null\n];\n```\n\n-----------\n\n## Custom settings\n\n### Settings for parse\n\n```php\n    // -------------------- settings for parse option --------------------\n\n    /**\n     * Stop parse option on found first argument.\n     *\n     * - Useful for support multi commands. eg: `top --opt ... sub --opt ...`\n     *\n     * @var bool\n     */\n    protected $stopOnFistArg = true;\n\n    /**\n     * Skip on found undefined option.\n     *\n     * - FALSE will throw FlagException error.\n     * - TRUE  will skip it and collect as raw arg, then continue parse next.\n     *\n     * @var bool\n     */\n    protected $skipOnUndefined = false;\n\n    // -------------------- settings for parse argument --------------------\n\n    /**\n     * Whether auto bind remaining args after option parsed\n     *\n     * @var bool\n     */\n    protected $autoBindArgs = true;\n\n    /**\n     * Strict match args number.\n     * if exist unbind args, will throw FlagException\n     *\n     * @var bool\n     */\n    protected $strictMatchArgs = false;\n\n```\n\n### Setting for render help\n\nsupport some settings for render help\n\n```php\n\n    // -------------------- settings for built-in render help --------------------\n\n    /**\n     * Auto render help on provide '-h', '--help'\n     *\n     * @var bool\n     */\n    protected $autoRenderHelp = true;\n\n    /**\n     * Show flag data type on render help.\n     *\n     * if False:\n     *\n     * -o, --opt    Option desc\n     *\n     * if True:\n     *\n     * -o, --opt STRING   Option desc\n     *\n     * @var bool\n     */\n    protected $showTypeOnHelp = true;\n\n    /**\n     * Will call it on before print help message\n     *\n     * @var callable\n     */\n    private $beforePrintHelp;\n\n```\n\n- custom help message renderer\n\n```php\n$fs-\u003esetHelpRenderer(function (\\Toolkit\\PFlag\\FlagsParser $fs) {\n    // render help messages\n});\n```\n\n-----------\n\n## Unit tests\n\n```bash\nphpunit --debug\n```\n\ntest with coverage:\n\n```bash\nphpdbg -dauto_globals_jit=Off -qrr $(which phpunit) --coverage-text\nphpdbg -dauto_globals_jit=Off -qrr $(which phpunit) --coverage-clover ./test/clover.info\n# use xdebug\nphpunit --coverage-clover ./test/clover.info\n```\n\n## Project use\n\nCheck out these projects, which use https://github.com/php-toolkit/pflag :\n\n- [inhere/console](https://github.com/inhere/console) Full-featured php command line application library.\n- [kite](https://github.com/inhere/kite) Kite is a tool for help development.\n- More, please see [Packagist](https://packagist.org/packages/toolkit/pflag)\n\n## License\n\n[MIT](LICENSE)\n","funding_links":[],"categories":["PHP"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphp-toolkit%2Fpflag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphp-toolkit%2Fpflag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphp-toolkit%2Fpflag/lists"}