Download the PHP package jbzoo/cli without Composer

JBZoo / Cli

• Why?
• Live Demo
  • Output regular messages
  • Progress Bar Demo
• Quck Start - Build your first CLI App
  • Installing
  • File Structure
  • Composer file
  • Binary file
  • Simple CLI Action
• Built-in Functionality
  • Sanitize input variables
  • Rendering text in different colors and styles
  • Verbosity Levels
  • Memory and time profiling
• Progress Bar
  • Simple example
  • Advanced usage
• Helper Functions
  • Regualar question
  • Ask user's password
  • Ask user to select the option
  • Represent a yes/no question
  • Rendering key=>value list
• Easy logging
  • Simple log
  • Crontab
  • Elatcisearch / Logstash (ELK)
• Multi processing
• Tips & Tricks
• Contributing
• Useful projects and links
• License
• See Also

Why?

The library greatly extends the functionality of CLI App and helps make creating new console utilities in PHP quicker and easier. Here's a summary of why this library is essential:

• Enhanced Functionality

  • The library supercharges Symfony/Console, facilitating a more streamlined development of console utilities.

• Progress Bar Improvements

  • Developers gain a refined progress bar suited for loop actions and enhanced with debugging information. This makes tracking task progress and diagnosing issues a breeze. See Live Demo.
  • $this->_($messages, $level, $context) as part of CliCommand instead of Symfony/Console $output->writeln().
  • cli($messages, $level, $context) as alias for different classes.
  • $this->progressBar(iterable|int $listOrMax, \Closure $callback, string $title = '') as part of CliCommand instead of Symfony/Console ProgressBar.

• Strict Type Conversion

  • One notable feature allows for the strict conversion of option values, ensuring data integrity and reducing runtime errors. See DemoOptionsStrictTypes.php.
  • Built-in validations for list of values. See Sanitize input variables.

• Styling and Output Customization

  • With built-in styles and color schemes, developers can make their console outputs more readable and visually appealing. See DemoStyles.php.

• Message Aliases

  • The library introduces powerful aliases for message outputs, allowing for concise and consistent command calls. This is especially helpful in maintaining clean code.

• Advanced Options

  • Features such as profiling for performance, timestamping, error muting, and specialized output modes (like cron and logstash modes) empower developers to refine their console outputs and diagnostics according to their specific needs.
  • Display timing and memory usage information with --profile option.
  • Show timestamp at the beginning of each message with --timestamp option.
  • Mute any sort of errors. So exit code will be always 0 (if it's possible) with --mute-errors.
  • None-zero exit code on any StdErr message with --non-zero-on-error option.
  • For any errors messages application will use StdOut instead of StdErr --stdout-only option (It's on your own risk!).
  • Disable progress bar animation for logs with --no-progress option.

• Versatile Output Modes

  • The library provides different output formats catering to various use cases. Whether you're focusing on user-friendly text, logs, or integration with tools like ELK Stack, there's an output mode tailored for you.
  • --output-mode=text. By default, text output format. Userfriendly and easy to read.
  • --output-mode=cron. It's basically focused on logs output. It's combination of --timestamp --profile --stdout-only --no-progress -vv --no-ansi.
  • --output-mode=logstash. It's basically focused on Logstash format for ELK Stack. Also, it means --stdout-only --no-progress -vv.
• Bonuses
  • There is a multiprocess mode (please don't confuse it with multithreading) to speed up work with a monotonous dataset.
  • Helper functions for user input in interactive mode.

Live Demo

Output regular messages

Progress Bar Demo

Quck Start - Build your first CLI App

Installing

The simplest CLI application has the following file structure. See the Demo App for more details.

File Structure

Composer file

./demo/composer.json

Binary file

Binary file: demo/my-app

Simple CLI Action

The simplest CLI action: ./demo/Commands/DemoSimple.php

Built-in Functionality

Sanitize input variables

As live-demo take a look at demo application - ./demo/Commands/DemoOptionsStrictTypes.php.

Try to launch ./my-app options-strict-types.

Rendering text in different colors and styles

There are list of predefined colors

There are list of predefined styles

Also, you can combine colors ans styles.

And predefined shortcuts for standard styles of Symfony Console

Verbosity Levels

Console commands have different verbosity levels, which determine the messages displayed in their output.

As live-demo take a look at demo application - Demo video.

Example of usage of verbosity levels

Memory and time profiling

As live-demo take a look at demo application - ./demo/Commands/DemoProfile.php.

Try to launch ./my-app profile --profile.

Progress Bar

As live-demo take a look at demo application - Live Demo.

You can consider this as a substitute for the long cycles you want to profile.

Keep in mind that there is an additional overhead for memory and runtime to calculate all the extra debugging information in --verbose mode.

Simple example

Advanced usage

Helper Functions

As live-demo take a look at demo application - ./demo/Commands/DemoHelpers.php.

Try to launch ./my-app helpers.

JBZoo/Cli uses Symfony Question Helper as base for aliases.

Regualar question

Ask any custom question and wait for a user's input. There is an option to set a default value.

Ask user's password

Ask a question and hide the response. This is particularly convenient for passwords. There is an option to set a random value as default value.

Ask user to select the option

If you have a predefined set of answers the user can choose from, you could use a method askOption which makes sure that the user can only enter a valid string from a predefined list. There is an option to set a default option (index or string).

Represent a yes/no question

Suppose you want to confirm an action before actually executing it. Add the following to your command.

Rendering key=>value list

If you need to show an aligned list, use the following code.

Easy logging

Simple log

Crontab

Just add the --output-mode=cron flag and save the output to a file. Especially, this is very handy for saving logs for Crontab.

Elatcisearch / Logstash (ELK)

Just add the --output-mode=logstash flag and save the output to a file. Especially, this is very handy for saving logs for ELK Stack.

Multi processing

There is a multiprocess mode (please don't confuse it with multithreading) to speed up work with a monotonous dataset. Basically, JBZoo\Cli will start a separate child process (not a thread!) for each dataset and wait for all of them to execute (like a Promise). This is how you get acceleration, which will depend on the power of your server and the data processing algorithm.

You will see a simple progress bar, but you won't be able to profile and log nicely, as it works for normal mode.

You can find examples here

• ./tests/TestApp/Commands/TestSleepMulti.php - Parent command
• ./tests/TestApp/Commands/TestSleep.php - Child command

Notes:

• Pay attention on the method executeOneProcess() and getListOfChildIds() which are used to manage child processes. They are inherited from CliCommandMultiProc class.
• Optimal number of child processes is Number of CPU cores - 1 . You can override this value by setting cli options. See them here ./src/CliCommandMultiProc.php.
• Be really careful with concurrency. It's not easy to debug. Try to use -vvv option to see all errors and warnings.

Tips & Tricks

• Use class \JBZoo\Cli\Codes to get all available exit codes.
• You can add extra context to any message. It will be serialized to JSON and displayed in the end of the message. Just use CliHelper::getInstance()->appendExtraContext(['section' => ['var' => 'value']]);
• You can define constant \JBZOO_CLI_TIMESTAMP_REAL=true to add timestamp_real as exta context. Sometimes it's useful for logstash if default value @timestamp doesn't work for you.

Contributing

Useful projects and links

• Symfony/Console Docs
• kevinlebrun/colors.php - New colors for the terminal
• php-school/cli-menu - Interactive menu with nested items
• nunomaduro/collision - Beautiful error reporting
• splitbrain/php-cli - Lightweight and no dependencies CLI framework
• thephpleague/climate - Allows you to easily output colored text, special formats
• Exit Codes With Special Meanings
• How to redirect standard (stderr) error in bash

License

MIT

See Also

• CI-Report-Converter - Converting different error reports for deep compatibility with popular CI systems.
• Composer-Diff - See what packages have changed after composer update.
• Composer-Graph - Dependency graph visualization of composer.json based on mermaid-js.
• Mermaid-PHP - Generate diagrams and flowcharts with the help of the mermaid script language.
• Utils - Collection of useful PHP functions, mini-classes, and snippets for every day.
• Image - Package provides object-oriented way to manipulate with images as simple as possible.
• Data - Extended implementation of ArrayObject. Use files as config/array.
• Retry - Tiny PHP library providing retry/backoff functionality with multiple backoff strategies and jitter support.
• SimpleTypes - Converting any values and measures - money, weight, exchange rates, length, ...