{"id":15389138,"url":"https://github.com/splitbrain/php-cli","last_synced_at":"2025-05-16T08:04:27.510Z","repository":{"id":43088253,"uuid":"58226993","full_name":"splitbrain/php-cli","owner":"splitbrain","description":"PHP library to build command line tools","archived":false,"fork":false,"pushed_at":"2024-06-02T17:11:27.000Z","size":654,"stargazers_count":167,"open_issues_count":2,"forks_count":38,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-10-29T20:00:01.491Z","etag":null,"topics":["library","php","php-cli","php-library"],"latest_commit_sha":null,"homepage":"http://splitbrain.github.io/php-cli/","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/splitbrain.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}},"created_at":"2016-05-06T18:27:54.000Z","updated_at":"2024-09-24T13:46:37.000Z","dependencies_parsed_at":"2024-01-17T13:31:24.758Z","dependency_job_id":"a3b138e1-64e8-40bb-af92-d4aea82cf4c0","html_url":"https://github.com/splitbrain/php-cli","commit_stats":{"total_commits":61,"total_committers":9,"mean_commits":6.777777777777778,"dds":0.4098360655737705,"last_synced_commit":"844609ef16b8486691b7fd892d54478918f27fe8"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/splitbrain%2Fphp-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/splitbrain%2Fphp-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/splitbrain%2Fphp-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/splitbrain%2Fphp-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/splitbrain","download_url":"https://codeload.github.com/splitbrain/php-cli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493378,"owners_count":22080126,"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":["library","php","php-cli","php-library"],"created_at":"2024-10-01T14:59:32.171Z","updated_at":"2025-05-16T08:04:22.499Z","avatar_url":"https://github.com/splitbrain.png","language":"PHP","readme":"# PHP-CLI\n\nPHP-CLI is a simple library that helps with creating nice looking command line scripts.\n\nIt takes care of\n\n- **option parsing**\n- **help page generation**\n- **automatic width adjustment**\n- **colored output**\n- **optional PSR3 compatibility**\n\nIt is lightweight and has **no 3rd party dependencies**. Note: this is for non-interactive scripts only. It has no readline or similar support.\n\n## Installation\n\nUse composer:\n\n```php composer.phar require splitbrain/php-cli```\n\n## Usage and Examples\n\nMinimal example:\n\n```php\n#!/usr/bin/php\n\u003c?php\nrequire __DIR__ . '/../vendor/autoload.php';\nuse splitbrain\\phpcli\\CLI;\nuse splitbrain\\phpcli\\Options;\n\nclass Minimal extends CLI\n{\n    // register options and arguments\n    protected function setup(Options $options)\n    {\n        $options-\u003esetHelp('A very minimal example that does nothing but print a version');\n        $options-\u003eregisterOption('version', 'print version', 'v');\n    }\n\n    // implement your code\n    protected function main(Options $options)\n    {\n        if ($options-\u003egetOpt('version')) {\n            $this-\u003einfo('1.0.0');\n        } else {\n            echo $options-\u003ehelp();\n        }\n    }\n}\n// execute it\n$cli = new Minimal();\n$cli-\u003erun();\n```\n\n![Screenshot](screenshot.png)\n\n\nThe basic usage is simple:\n\n- create a class and ``extend splitbrain\\phpcli\\CLI``\n- implement the ```setup($options)``` method and register options, arguments, commands and set help texts\n    - ``$options-\u003esetHelp()`` adds a general description\n    - ``$options-\u003eregisterOption()`` adds an option\n    - ``$options-\u003eregisterArgument()`` adds an argument\n    - ``$options-\u003eregisterCommand()`` adds a sub command\n- implement the ```main($options)``` method and do your business logic there\n    - ``$options-\u003egetOpts`` lets you access set options\n    - ``$options-\u003egetArgs()`` returns the remaining arguments after removing the options\n    - ``$options-\u003egetCmd()`` returns the sub command the user used\n- instantiate your class and call ```run()``` on it\n\nMore examples can be found in the examples directory. Please refer to the [API docs](https://splitbrain.github.io/php-cli/)\nfor further info.\n\n## Exceptions\n\nBy default, the CLI class registers an exception handler and will print the exception's message to the end user and\nexit the programm with a non-zero exit code. You can disable this behaviour and catch all exceptions yourself by\npassing false to the constructor.\n\nYou can use the provided ``splitbrain\\phpcli\\Exception`` to signal any problems within your main code yourself. The\nexception's code will be used as the exit code then.\n\nStacktraces will be printed on log level `debug`. \n\n## Colored output\n\nColored output is handled through the ``Colors`` class. It tries to detect if a color terminal is available and only\nthen uses terminal colors. You can always suppress colored output by passing ``--no-colors`` to your scripts.\nDisabling colors will also disable the emoticon prefixes.\n\nSimple colored log messages can be printed by you using the convinence methods ``success()`` (green), ``info()`` (cyan),\n``error()`` (red) or ``fatal()`` (red). The latter will also exit the programm with a non-zero exit code.\n\nFor more complex coloring you can access the color class through ``$this-\u003ecolors`` in your script. The ``wrap()`` method\nis probably what you want to use.\n\nThe table formatter allows coloring full columns. To use that mechanism pass an array of colors as third parameter to\nits ``format()`` method. Please note that you can not pass colored texts in the second parameters (text length calculation\nand wrapping will fail, breaking your texts).\n\n## Table Formatter\n\nThe ``TableFormatter`` class allows you to align texts in multiple columns. It tries to figure out the available\nterminal width on its own. It can be overwritten by setting a ``COLUMNS`` environment variable.\n\nThe formatter is used through the ``format()`` method which expects at least two arrays: The first defines the column\nwidths, the second contains the texts to fill into the columns. Between each column a border is printed (a single space\nby default).\n\nSee the ``example/table.php`` for sample usage.\n\nColumns width can be given in three forms:\n\n- fixed width in characters by providing an integer (eg. ``15``)\n- precentages by provifing an integer and a percent sign (eg. ``25%``)\n- a single fluid \"rest\" column marked with an asterisk (eg. ``*``)\n\nWhen mixing fixed and percentage widths, percentages refer to the remaining space after all fixed columns have been\nassigned.\n\nSpace for borders is automatically calculated. It is recommended to always have some relative (percentage) or a fluid\ncolumn to adjust for different terminal widths.\n\nThe table formatter is used for the automatic help screen accessible when calling your script with ``-h`` or ``--help``.\n\n## PSR-3 Logging\n\nThe CLI class is a fully PSR-3 compatible logger (printing colored log data to STDOUT and STDERR). This is useful when\nyou call backend code from your CLI that expects a Logger instance to produce any sensible status output while running.\n\nIf you need to pass a class implementing the `Psr\\Log\\LoggerInterface` you can do so by inheriting from one of the two provided classes implementing this interface instead of `splitbrain\\phpcli\\CLI`.\n\n  * Use `splitbrain\\phpcli\\PSR3CLI` if you're using version 2 of PSR3 (PHP \u003c 8.0)\n  * Use `splitbrain\\phpcli\\PSR3CLIv3` if you're using version 3 of PSR3 (PHP \u003e= 8.0) \n\nThe resulting object then can be passed as the logger instance. The difference between the two is in adjusted method signatures (with appropriate type hinting) only. Be sure you have the suggested `psr/log` composer package installed when using these classes.\n\nNote: if your backend code calls for a PSR-3 logger but does not actually type check for the interface (AKA being LoggerAware only) you can also just pass an instance of `splitbrain\\phpcli\\CLI`.\n\n## Log Levels\n\nYou can adjust the verbosity of your CLI tool using the `--loglevel` parameter. Supported loglevels are the PSR-3\nloglevels and our own `success` level:\n\n* debug\n* info\n* notice      \n* success (this is not defined in PSR-3)\n* warning\n* error\n* critical\n* alert\n* emergency\n\n![Screenshot](screenshot2.png)\n\nConvenience methods for all log levels are available. Placeholder interpolation as described in PSR-3 is available, too.\nMessages from `warning` level onwards are printed to `STDERR` all below are printed to `STDOUT`. \n\nThe default log level of your script can be set by overwriting the `$logdefault` member.\n\nSee `example/logging.php` for an example.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsplitbrain%2Fphp-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsplitbrain%2Fphp-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsplitbrain%2Fphp-cli/lists"}