{"id":23893318,"url":"https://github.com/sumpygump/qi-console","last_synced_at":"2025-04-10T12:52:26.261Z","repository":{"id":5921215,"uuid":"7140816","full_name":"sumpygump/qi-console","owner":"sumpygump","description":"PHP library for dealing with the console or terminal","archived":false,"fork":false,"pushed_at":"2024-02-21T01:32:22.000Z","size":87,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-24T11:38:29.198Z","etag":null,"topics":["php","terminal","terminfo"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sumpygump.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-12-13T01:28:57.000Z","updated_at":"2024-07-13T21:07:29.000Z","dependencies_parsed_at":"2022-09-06T07:41:48.466Z","dependency_job_id":null,"html_url":"https://github.com/sumpygump/qi-console","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumpygump%2Fqi-console","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumpygump%2Fqi-console/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumpygump%2Fqi-console/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sumpygump%2Fqi-console/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sumpygump","download_url":"https://codeload.github.com/sumpygump/qi-console/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248220467,"owners_count":21067315,"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":["php","terminal","terminfo"],"created_at":"2025-01-04T14:17:45.533Z","updated_at":"2025-04-10T12:52:26.241Z","avatar_url":"https://github.com/sumpygump.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Qi Console\n==========\n\nQi Console provides PHP library classes for dealing with the console or terminal.\n\n[![Build Status](https://travis-ci.org/sumpygump/qi-console.png)](https://travis-ci.org/sumpygump/qi-console)\n\n## Installation with Composer\n\nUse composer to include the `Qi_Console` library in a project.\n\nAdd the following composer.json file to your project directory:\n\n```json\n{\n    \"require\": {\n        \"sumpygump/qi-console\": \"dev-master\"\n    }\n}\n```\n    \nThen run composer install to fetch.\n\n    $ composer.phar install\n\nIf you don't have composer already installed, this is my recommendation for\ninstalling it. See\n[getcomposer.org installation instructions](http://getcomposer.org/doc/00-intro.md#globally).\n\n```\n$ curl -sS https://getcomposer.org/installer | php\n$ sudo mv composer.phar /usr/local/bin/composer\n```\n\nOnce the files have been composed with the `composer install` command, you can\nuse any of the `Qi_Console_` classes after composer's autoloader is included.\n\n```php\nrequire 'vendor/autoload.php';\n\n$terminal = new Qi_Console_Terminal();\n// ...\n```\n\n## Manual Installation\n\nYou can also download the files and place them in a library folder. If you do\nthis, be sure to update your autoloader to handle the `Qi_Console_*` classes or\nelse manually include the files of the classes you'll need.\n\n# Documentation\n\n## ArgV\n\nArgV provides a way to assign and gather command line arguments\n\nIt will parse and assign option flags and arguments passed\nin as command line arguments\n\nExamples of script arguments it can potentially parse:\n\n - short option (-f) : can be grouped (-fvz)\n - long option (--flag)\n - short parameter (-p value)\n - short parameter shunt (-pvalue)\n - long parameter (--param value)\n - long parameter shunt (--param=value)\n - standalone argument (filename)\n\n### Usage \n\nThe constructor takes two arguments: `$argv` and `$rules`\n\nThe argument `$argv` is an array of arguments from the command line that is parsed by PHP\nwhen the script is invoked. For example, when you invoke a PHP script with the\nfollowing:\n\n    php myscript.php -v --flag --param=value okay\n\nThen in your script PHP will provide a variable `$argv` representative of the\nelements of the arguments passed in as an array like this:\n\n```php\narray(\n    'myscript.php',\n    '-v',\n    '--flag',\n    '--param=value',\n    'okay',\n);\n```\n\nThe argument `$rules` is a definition of options and help messages. The format\nis a key value array where the key is the option definition (possible\nparameters) and the value is the help message for that option.\n\nHere are some examples illustrating the possible rules keys:\n\n - `v` - a single letter defines a single short option flag, so this\n   corresponds to the option `-v`\n - `flag` - a single word defines a long option flag (`--flag`)\n - `help|h` - a word, then vertical bar, then a single letter will define a\n   long and short option (`--help` and `-h`)\n - `name|n:` - a key that ends with a colon character (`:`) indicates a\n   required parameter. This allows the following: `--name=value`, `-n=value`,\n   `--name value`, `-n value` and `-nvalue`. If the arguments for this option\n   don't contain a parameter this will throw a `Qi_Console_ArgVException`.\n - `arg:filename` - a key that begin with the string `arg:` defines a\n   non-option argument (ones that don't begin with a `-`). The word after the\n   colon is the name of the argument as it will appear in ArgV. The `arg:`\n   parameters in `$argv` will be assigned in the order they appear in the rules\n   array. So the first non-option argument in `$argv` will be assigned to the\n   first `arg:` key name, etc.\n\nHere is some example code that illustrates the above:\n\n```php\n// Example rules with some help messages\n$rules = array(\n    'v' =\u003e 'Use verbose messaging',\n    'o' =\u003e 'Another random option',\n    'flag' =\u003e 'Flag something as special',\n    'name|n:' =\u003e 'Provide a name to use',\n    'arg:filename' =\u003e 'Filename to parse',\n);\n\n// Our example input\n// php scriptname -v --flag --name \"a name\" filename.txt\n$argv = array(\n    'scriptname', // The first argument is always ignored by ArgV\n    '-v',\n    '--flag',\n    '--name',\n    '\"a name\"',\n    'filename.txt',\n);\n\n$arguments = new Qi_Console_ArgV($argv, $rules);\n\n// Now we can reference the following:\n$arguments-\u003ev; // true\n$arguments-\u003eo; // false\n$arguments-\u003eflag; // true\n$arguments-\u003ename; // equal to 'a name'\n$arguments-\u003efilename; // equal to 'filename.txt'\n```\n\nNote that any additional options that were not defined in the rules array, but\nwere passed in as input will result in sensible defaults, so options\nwill default to true and named options (`--anothername=value`) will result in\nthe values passed in (`$arguments-\u003eanothername == 'value'`). Additional\nnon-option arguments will be available as `$arguments-\u003e__arg2`,\n`$arguments-\u003e__arg3`, etc.\n\n## Client\n\nThe `Qi_Console_Client` class provides a base console client that can be used\nto create command line clients. It takes input as `$argv` and a Terminal object\nwhich can be used to output messages back to the terminal.\n\nMethods:\n\n    __construct()\n    _displayError()\n    _displayMessage()\n    _displayWarning()\n    _halt()\n    _resetTty()\n    _safeExit()\n    init()\n\n### Basic Usage\n\n```php\nclass MyClient extends Qi_Console_Client\n{\n    public function init()\n    {\n        // Initialization logic\n    }\n\n    public function execute()\n    {\n        // Execute the main logic of this client\n        // Use $this-\u003e_args (ArgV object) to handle input and react\n        // Use $this-\u003e_displayWarning() to output warning message to user\n        // etc.\n    }\n}\n\n$arguments = new Qi_Console_ArgV($argv, $rules);\n$terminal = new Qi_Console_Terminal();\n\n$myClient = new MyClient($arguments, $terminal);\n$myClient-\u003eexecute();\n```\n\n## ExceptionHandler\n\nThe exception handler provides a way to handle exceptions from your console\napplication. It uses the Terminal object to output pretty messages.\n\n```php\n$terminal = new Qi_Console_Terminal();\n$exceptionHandler = new Qi_Console_ExceptionHandler($terminal);\n$exceptionHandler-\u003ebindHandlers();\n\n// Now any time an exception is thrown, it will output a pretty message\n// with colors and exit.\n```\n    \n## Menu\n\n`Qi_Console_Menu` provides a way to prompt a user with a menu and receive\ninput. Please see the code for documentation.\n\n## ProgressBar\n\n`Qi_Console_ProgressBar` provides the ability to display a progress bar in the\nterminal. Please see the code for documentation.\n\n## Std\n\n`Qi_Console_Std` is a wrapper for stdin, stdout and stderr.\n \nThis class provides methods for sending and receiving input from stdin and\noutput to stdout and stderr.\n\n```php\n// Receive input from STDIN\n$input = Qi_Console_Std::in();\n\n// Output to STDOUT\nQi_Console_Std::out('Some text');\n\n// Output to STDERR\nQi_Console_Std::err('Error output');\n```\n\n## Tabular\n\n`Qi_Console_Tabular` generates ascii tables for displaying tabular data.\n\n```php\n// Define the table data\n$tableData = array(\n    array('John', '28', 'Green'),\n    array('Hannah', '7', 'Violet'),\n    array('Michael', '43', 'Red'),\n);\n\n// Define the headers for the columns\n$headers = array(\n    'Name',\n    'Age',\n    'Favorite Color',\n);\n\n// Define optional alignment for columns\n$alignment = array(\n    'L',\n    'R',\n    'L'\n);\n\n$tabular = new Qi_Console_Tabular(\n    $tableData,\n    array(\n        'headers'   =\u003e $headers,\n        'cellalign' =\u003e $alignment,\n    )\n);\n\n$tabular-\u003edisplay();\n```\n\nThis will output the following table:\n\n    +--------------------------------------+\n    |  Name     |  Age  |  Favorite Color  |\n    +--------------------------------------+\n    |  John     |   28  |  Green           |\n    |  Hannah   |    7  |  Violet          |\n    |  Michael  |   43  |  Red             |\n    +--------------------------------------+\n\n## Terminal and Terminfo\n\n`Qi_Console_Terminal` is a wrapper for `Qi_Console_Terminfo` which uses the\nUNIX terminfo mapping database to provide functionality for outputting escape\nsequences to the terminal. It provides a low-level robust way using terminal\nfeatures such as outputting colors.\n\nFor more information about terminfo, check out these resources:\n\n - [Man page for terminfo](http://invisible-island.net/ncurses/man/terminfo.5.html)\n - [Terminal Capabilities](https://en.wikipedia.org/wiki/Terminal_capabilities)\n\n### Basic Usage\n\n```php\n$terminal = new Qi_Console_Terminal();\n\n// Clear the screen\n$terminal-\u003eclear();\n\n$terminal-\u003eset_fgcolor(1);\necho \"Text is now red.\\n\";\n\n$terminal-\u003eset_fgcolor(2);\necho \"Text is now green.\\n\";\n\n$terminal-\u003ebold_type();\necho \"Text is now bold.\\n\";\n\n$terminal-\u003ecenter_text(\"This text is centered.\");\n\n// This is using the terminfo capability \"Original Pair\" to set the colors\n// back to default.\n$terminal-\u003eop();\necho \"Now text is back to default color.\\n\";\n\n// This is using the terminfo capability sgr0 which turns off all text\n// attributes, meaning it is not bold anymore.\n$terminal-\u003esgr0();\necho \"Now text is not bold anymore.\\n\";\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsumpygump%2Fqi-console","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsumpygump%2Fqi-console","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsumpygump%2Fqi-console/lists"}