Download the PHP package eftec/clione without Composer

CliOne

This library helps to create command line (CLI) operator for PHP in Windows, Mac and Linux

[]() []() []() []() []()

Features

✅ Windows, Linux and Mac Compatible.

✅ This library truly minimalist and simple, it only consists of 2 classes and nothing more and no external dependency.

✅ Arguments & user input

✅ This library was aimed to (optionally) fallback to user-input if the argument is missing.

✅ Colors available

✅ The design is mostly fluent (it adjusts to the width of the screen)

✅ Validation of values

✅ Support NO_COLOR environment variable. See https://no-color.org/

Getting started

Add the library using composer:

composer require eftec/clione

And create a new instance of the library

Usage

For example, let's say we need to create a CLI code to read an information and save into a file.

We have two arguments, the first (read) is in the first position, and it doesn't have any "-". The second is "-o" that it is our flag with a value.

So we could create our arguments.

And we could evaluate as

It will return false if we don't set a value, and it will return the value it we set it.

The parameters are created and evaluated separately because it allows to do more powerful operations with it.

For example, sometimes we want to show the help (the list of parameters available) without evaluating the parameters.

Ok, but now what if we want to create an alias of "-o"

So we could call using this line

If the parameter is a flag, then the alias is a longflag ("--"). If the parameter is a longflag then the alias is a flag.

But let's say we need to ask for a password, however we want to be entered interactively.

So it will look like:

Now, let's say something more advanced, multiple options, we want to select the type of file: json, csv, html and xml

Our code

And the result:

List of values are divided in two values, the visual value (simply called value), and the key-value.. In this example, "csv" is a value and its key-value is "2".

The list of values allows associative arrays and indexed arrays. Indexed arrays are renumbered to start in 1.

You could also enter

php .\basic.php read -o result.json -pwd 123 -type json

Now, you can show the parameters ("show the syntax help") as follows:

But it will look plain.

It is because you can add a description, change the question and add more help information

So it will look like: (in colors)

There are more operations available but the basic is there.

Table of contents

• CliOne
  • Features
  • Getting started
  • Usage
• Table of contents
  • Flow
  • Input as arguments
  • Input interactive
  • User input (interactive)
  • Customize user input
  • CliOne Class
  • Method __construct()
    • Parameters:
  • Method getWindowsVersion()
  • Method instance()
    • Parameters:
  • Method hasInstance()
  • Method hasMenu()
  • Method clearMenu()
    • Parameters:
  • Method addMenu()
    • Parameters:
  • Method addMenuItem()
    • Parameters:
  • Method addMenuItems()
    • Parameters:
  • Method addMenuService()
    • Parameters:
  • Method evalMenu()
    • Parameters:
  • Method getErrorType()
  • Method getMemory()
  • Method setVariable()
    • Parameters:
  • Method getVariable()
    • Parameters:
  • Method addVariableCallBack()
    • Parameters:
  • Method callVariablesCallBack()
  • Method hasColorSupport()
  • Method testArguments()
    • Parameters:
  • Method testUserInput()
    • Parameters:
  • Method setMemory()
    • Parameters:
  • Method setErrorType()
    • Parameters:
  • Method findVendorPath()
    • Parameters:
  • Method createParam()
    • Parameters:
  • Method createOrReplaceParam()
  • Method downLevel()
    • Parameters:
  • Method evalParam()
    • Parameters:
  • Method throwError()
    • Parameters:
  • Method showWarning()
    • Parameters:
  • Method addHistory()
    • Parameters:
  • Method setHistory()
    • Parameters:
  • Method clearHistory()
  • Method listHistory()
  • Method getArrayParams()
    • Parameters:
  • Method getColSize()
  • Method getParameter()
    • Parameters:
  • Method getValue()
    • Parameters:
  • Method readArgument()
    • Parameters:
  • Method showHelp()
    • Parameters:
  • Method makeBigWords()
    • Parameters:
  • Method getValueKey()
    • Parameters:
  • Method isCli()
  • Method getSTDIN()
  • Method readData()
    • Parameters:
  • Method readDataPHPFormat()
    • Parameters:
  • Method isParameterPresent()
    • Parameters:
  • Method addExtensionFile()
    • Parameters:
  • Method saveData()
    • Parameters:
  • Method saveDataPHPFormat()
    • Parameters:
  • Method setAlign()
    • Parameters:
  • Method setArrayParam()
    • Parameters:
  • Method reconstructPath()
    • Parameters:
  • Method getPhpOriginalFile()
  • Method setPhpOriginalFile()
    • Parameters:
  • Method setColor()
    • Parameters:
  • Method setParam()
    • Parameters:
  • Method setParamUsingArray()
    • Parameters:
  • Method createContainer()
    • Parameters:
  • Method getValueAsArray()
    • Parameters:
  • Method setPatternTitle()
    • Parameters:
  • Method setPatternCurrent()
    • Parameters:
  • Method setPatternSeparator()
    • Parameters:
  • Method setPatternContent()
    • Parameters:
  • Method setStyle()
    • Parameters:
  • Method show()
    • Parameters:
  • Method showBread()
    • Parameters:
  • Method showCheck()
    • Parameters:
  • Method showFrame()
    • Parameters:
  • Method showLine()
    • Parameters:
  • Method clearScreen()
  • Method cursorHome()
  • Method cursorMove()
    • Parameters:
  • Method bell()
  • Method getCursorPosition()
  • Method showMessageBox()
    • Parameters:
  • Method alignLinesVertically()
    • Parameters:
  • Method maxWidth()
  • Method showParamSyntax()
    • Parameters:
  • Method showParamSyntax2()
    • Parameters:
  • Method setDefaultStream()
    • Parameters:
  • Method setNoColor()
    • Parameters:
  • Method isNoColor()
  • Method setNoANSI()
    • Parameters:
  • Method isNoANSI()
  • Method wrapLine()
    • Parameters:
  • Method showProgressBar()
    • Parameters:
  • Method getPageSize()
  • Method showTable()
    • Parameters:
  • Method showValuesColumn()
    • Parameters:
  • Method showWaitCursor()
    • Parameters:
  • Method hideWaitCursor()
  • Method hideCursor()
  • Method showCursor()
  • Method showparams()
  • Method showParamValue()
    • Parameters:
  • Method strlen()
    • Parameters:
  • Method removechar()
    • Parameters:
  • Method upLevel()
    • Parameters:
  • Method getCh()
    • Parameters:
  • Method colorText()
    • Parameters:
  • Method colorLess()
    • Parameters:
  • Method colorMask()
    • Parameters:
  • Method initialEndStyle()
    • Parameters:
  • Method replaceCurlyVariable()
    • Parameters:
  • menu
  • addMenu()
  • addMenuItem()
  • addMenuItems()
  • evalMenu()
  • clearMenu()
  • example
  • Examples
  • Example using arguments
  • Example using user input
  • Example with a game
  • Example colors
  • Example tables
  • Types of user input
  • Types of colors
  • Definitions
  • debug
  • Compatibility
  • Changelog

Flow

• (optional) you can set the current value using the method setParam()
• If the type of parameter is not "onlyinput" and "none", then it reads the parameter
  • Example: php program.php -param1 value --param2 -param3="hello world" parampositional
• If the parameter is found, then it is returned, end of the flow.
• If the parameter is not found then
  • If setCurrentAsDefault() is set, and the current value is not null, then the default value is the current value.
  • Otherwise, the default value is the value set using the method setDefault(). If none, then it uses null.
• if input is true setInput(true) then it asks to user-input the value
  • if the user doesn't fill the information, then it returns the default value (if any), end of the flow
  • if the user fills the information, but it is incorrect, then it asks again and again.
  • if the user fills the right information, then it returns this value, end of the flow
• if input is true setInput(false) then
  • Note: we were unable to read the values of the argument, and we don't want to read from user input.
  • it returns the default value, and it could raise an error, end of the flow

Note:

• isRequired() if the value is missing, then it shows an error.
• setAllowEmpty() if the value is empty (not missing), then it allows to enter an empty value

Input as arguments

The system allows reading multiple types of arguments

• first: this argument does not have value, and it is position (in the very first position), it must be not be prefixed with a "-", otherwise it would be considered a flag instead of a positional argument.

• command: it is similar to first, but it does not compare the name of the argument.

• second: this argument is also positional (second position) and does not have any value

• last: this argument is also positional, and it is always at the latest argument

• flag: the argument is prefixed with a single "-". This argument not need to be a single character.

• longflag: the argument is prefixed with a double "--"

• onlyinput/none: the system never read it as argument, so it could be user-input.
  • none means that the argument is only user-input, and it must not be stored.

The argument could be created as:

And it could be read as:

Now, what if you want to create multiples alias for the same parameter.

Input interactive

There are several configuration to set an input interactively.

By default, every parameter is read as argument. If the value is read as argument, then it is not asked interactively.

However, if the parameter is of the type "none" or "onlyinput", then they are only obtained by user input ( interactively).

Example:

User input (interactive)

With the method setInput() we set that this parameter could also be read interactively.

Example, let's say the next example:

Now, this input accepts any kind of text. But there is many kind of user input.

Option returns a value and a value-key. Value is the content visible. And value-key, is the content selected by the user.

Example Option:

Example Multiple:

Customize user input

It is possible to customize the input by changing the help description, changing the question, showing an example or showing a value to the argument

CliOne Class

CliOne - A simple creator of command-line argument program.

Method __construct()

The constructor. If there is an instance, then it replaces the instance.

Parameters:

• $origin you can specify the origin script file. If you specify the origin script then, isCli will only return true if the file is called directly using its file. (string|null)
• $ignoreCli if true, then it will run no matter if it is running on cli or not. (bool)

Method getWindowsVersion()

It returns the current Windows version as a decimal number.
If no version is found then it returns 6.1 (Windows 7).
Windows 10 and Windows 11 versions are returned as 10.xxxx instead of 10.0.xxxx

Method instance()

It gets the current instance of the library.
If the instance does not exist, then it is created

Parameters:

• $origin you can specify the origin script file. If you specify the origin script then, isCli will only return true if the file is called directly using its file. (string|null)

Method hasInstance()

Returns true if there is an instance of CliOne.

Method hasMenu()

It returns true if CliOne has a menu defined. It will return false if there is no menu or there is no instance.

Method clearMenu()

It clears a menu and the services associated.

Parameters:

• $idMenu If null, then it clears all menus (string|null)

Method addMenu()

It adds a new menu that could be called by evalMenu()
Example:

Parameters:

• $idMenu The unique name of the menu (string)
• $headerFunction Optional, the name of the method called every time the menu is displayed
  The method called must have a prefix menu.Ex:"opt1",method:menuopt1" If $headerFunction is callable, then it calls the function. (string|null|callable)
• $footerFunction Optional, the name of the method called every time the menu end its display. The method called must have a prefix "menu".
  If $footerFunction is callable, then it calls the function (string|null|callable)
• $question The input question. (string)
• $size =['option','option2','option3','option4','wide-option','wide-option2'][$i] The size of the option menu. (string)

Method addMenuItem()

It adds a menu item.
Example:

Parameters:

• $idMenu The unique name of the menu (string)
• $indexMenuItem The unique index of the menu. It is used for selection and action (if no action is supplied). (string)
• $description The description of the menu (string)
• $action The action is the method called (the method must have a prefix "menu").
  If action starts with "navigate:" then it opens the menu indicated.
  If action is "exit:" then exit of the menu.
  If action is callable, then it calls the function (string|null|callable)

Method addMenuItems()

It adds multiples items to a menu
Example:

Parameters:

• $idMenu The unique name of the menu (string)
• $items An associative array with the items to add. Examples:
  [index=>[description,action]]
  [index=>description]
  (array|null)

Method addMenuService()

It adds a service object to be evaluated when we run evalMenu()
You can add menu services. Every service is evaluated in order, so if both service objects has the same method, then it is only called by the first object.
If evalMenu() uses a service then, the services defined here are ignored.
Example:

Parameters:

• $idMenu The unique name of the menu (string)
• $service The service object or the name of the class.
  If it is a name of a class, then it creates an instance of it. (object|string)

Method evalMenu()

Eval (executes) a menu previously defined.
Example:

Parameters:

• $idMenu The unique name of the menu (string)
• $caller The caller object(s). It is used to the events and actions.
  If null, then it use the services defined by addMenuService();
  If it is an array, then it calls the first object that has the method
  If this argument is used then addMenuService() is ignored (object|null|array)

Method getErrorType()

Method getMemory()

Method setVariable()

It sets a value into an array.

Parameters:

• $variableName the name of the variable. If the variable exists, then it is replaced. (string)
• $value the value to assign. (mixed)
• $callBack if the value is true (default), then every modification (if the value is changed) will call the functions defined in addVariableCallBack()
  if fallse, then it does not call the callback functions. (bool)

Method getVariable()

It gets the value of a variable

Parameters:

• $variableName The name of the variable (string)
• $valueIfNotFound If not found then it returns this value (mixed|null)

Method addVariableCallBack()

It adds a callback function.
Example:

This function is called every setVariable() if the value is different as the defined.

Parameters:

• $callbackName the name of the function. If the function exists, then it is replaced. (string)
• $function If the function is null, then it deleted the function assigned.
  The function could be defined using an argument of the type CliOne. (callable|null)

Method callVariablesCallBack()

It calls the callback functions. Usually they are called every time we setVariable() (and the value is changed).

Method hasColorSupport()

This function is based in Symfony

Method testArguments()

It is used for testing. You can simulate arguments using this function
This function must be called before the creation of the instance

Parameters:

• $arguments param array $arguments (array)

Method testUserInput()

It is used for testing. You can simulate user-input using this function
This function must be called before every interactivity
This function is not resetted automatically, to reset it, set $userInput=null

Parameters:

• $userInput param ?array $userInput (?array)
• $throwNoInput (def:true) if true then it throws an exception if not input
  if false, then if no more input then it cleans the userinput (bool)

Method setMemory()

It sets the value stored into the memory stream
If the memory stream has values, then they are deleted and replaced.

Parameters:

• $memory The value to store (string)

Method setErrorType()

It sets if you want to display errors or not. This flag is reseted every time it is used.

Parameters:

• $errorType =['silent','show','throw'][$i] (default is show) (string)

Method findVendorPath()

It finds the vendor path starting from a route. The route must be inside the application path.

Parameters:

• $initPath the initial path, example DIR, getcwd(), 'folder1/folder2'. If null, then DIR (?string)

Method createParam()

It creates a new parameter to be read from the command line and/or to be input manually by the user
Example:

Parameters:

• $key The key or the parameter. It must be unique. (string)
• $alias A simple array with the name of the arguments to read without "-" or flag: (default) it reads a flag "php program.php -thisflag value"
  first: it reads the first argument "php program.php thisarg" (without value)
  second: it reads the second argument "php program.php sc1 thisarg" (without value)
  last: it reads the second argument "php program.php ... thisarg" (without value)
  longflag: it reads a longflag "php program --thislongflag value
  last: it reads the second argument "php program.php ... thisvalue" (without value)
  onlyinput: the value means to be user-input, and it is stored
  none: the value it is not captured via argument, so it could be user-input, but it is not stored
  none parameters could always be overridden, and they are used to "temporary" input such as validations (y/n). (array|string)
• $type =['command','first','last','second','flag','longflag','onlyinput','none'][$i]
  "-"
  if the type is a flag, then the alias is a double flag "--".
  if the type is a double flag, then the alias is a flag. (string)
• $argumentIsValueKey true the argument is value-key
  false (default) the argument is a value (bool)

Method createOrReplaceParam()

Method downLevel()

Down a level in the breadcrub.
If down more than the number of levels available, then it clears the stack.

Parameters:

• $number number of levels to down. (int)

Method evalParam()

It evaluates the parameters obtained from the syntax of the command.
The parameters must be defined before call this method
Example:

Parameters:

• $key the key to read.
  If $key='*' then it reads the first flag and returns its value (if any). (string)
• $forceInput it forces input no matter if the value is already inserted. (bool)
• $returnValue If true, then it returns the value obtained.
  If false (default value), it returns an instance of CliOneParam. (bool)

Method throwError()

It throws an error. Depending on the type, it could show an error or throw a runtime exception.

Parameters:

• $msg param string $msg (string)

Method showWarning()

It shows a warning

Parameters:

• $msg param array|string $msg (array|string)

Method addHistory()

Add a value to the history

Parameters:

• $prompt the value(s) of the history to add (string|array)

Method setHistory()

It sets the history (deleting the old history) with the new values

Parameters:

• $prompt param string|array $prompt (string|array)

Method clearHistory()

It clears the global history (if any).

Method listHistory()

It retrieves the global history (if any)

Method getArrayParams()

It returns an associative array with all the parameters of the form [key=>value]
Parameters of the type "none" are ignored

Parameters:

• $excludeKeys you can add a key that you want to exclude. (array)

Method getColSize()

It returns the number of columns present on the screen. The columns are calculated in the constructor.

Method getParameter()

It gets the parameter by the key or an empty parameter with a null key if null.

Parameters:

• $key the key of the parameter (string)

Method getValue()

It reads a value of a parameter. Example:

Parameters:

• $key the key of the parameter to read the value (string)

Method readArgument()

It reads a parameter as an argument or flag.

Parameters:

• $parameter param CliOneParam $parameter (CliOneParam)

Method showHelp()

It shows the help

Parameters:

• $parameter param CliOneParam $parameter (CliOneParam)
• $verbose param bool $verbose (bool)

Method makeBigWords()

Parameters:

• $word the words to display. (string)
• $font =['atr','znaki'][$i] (string)
• $trim if true then, if the first line and/or the last line is empty, then it is removed. (bool)
• $bit1 the visible character, if null then it will use a block code (?string)
• $bit0 the invisible character (string)

Method getValueKey()

It reads the value-key of a parameter selected. It is useful for a list of elements.
Example:

Parameters:

• $key the key of the parameter to read the value-key (string)

Method isCli()

It will return true if the PHP is running on CLI
If the constructor specified a file, then it is also used for validation. Example:

Method getSTDIN()

It gets the STDIN exclusively if the value is passed by pipes. If not, it returns null;

Method readData()

It reads information from a file. The information will be de-serialized.

Parameters:

• $filename the filename with or without extension. (string)
• $defaultExtension the default extension. (string)

Method readDataPHPFormat()

It reads information from a file. The information is evaluated, so the file must be safe.

Parameters:

• $filename the filename with or without extension. (string)
• $defaultExtension the default extension. (string)

Method isParameterPresent()

Returns true if the parameter is present with or without data.
The parameter is not changed, neither the default values nor user input are applied
Returned Values:

• none the value is not present, ex:
• empty the value is present but is empty, ex: -arg1
• value the value is present, and it has a value, ex: -arg1 value

Parameters:

• $key param string $key (string)

Method addExtensionFile()

Util class. It adds a default extension to a filename only if the filename doesn't have extension.

Parameters:

• $filename The filename full or partial, example "file.jpg", "file", "/folder/file" (string)
• $extension The extension to add including the dot, example ".ext".
  The default value is ".config.php" (string)

Method saveData()

It saves the information into a file. The content will be serialized.

Parameters:

• $filename the filename (without extension) to where the value will be saved. (string)
• $content The content to save. It will be serialized. (mixed)
• $defaultExtension The default extension. (string)

Method saveDataPHPFormat()

It saves the information into a file. The content will be converted into a PHP file.
Example:

Parameters:

• $filename the filename (without extension) to where the value will be saved. (string)
• $content The content to save. It will be serialized. (mixed)
• $defaultExtension The default extension. (string)
• $namevar The name of the variable, excample: config or $config (string)

Method setAlign()

It sets the alignment. This method is stackable.
Example:

Parameters:

• $title =['left','right','middle'][$i] the alignment of the title (string)
• $content =['left','right','middle'][$i] the alignment of the content (string)
• $contentNumeric =['left','right','middle'][$i] the alignment of the content (numeric) (string)

Method setArrayParam()

It sets the parameters using an array of the form [key=>value]
It also marks the parameters as missing=false

Parameters:

• $array the associative array to use to set the parameters. (array)
• $excludeKeys you can add a key that you want to exclude.
  If the key is in the array and in this list, then it is excluded (array)
• $includeKeys the whitelist of elements that only could be included.
  Only keys that are in this list are added. (array|null)

Method reconstructPath()

It is used internally to reconstruct the path of the current script.

Parameters:

• $includePHP param bool $includePHP (bool)
• $trimArguments param int $trimArguments (int)

Method getPhpOriginalFile()

It gets the php original file

Method setPhpOriginalFile()

It sets the php original file

Parameters:

• $phpOriginalFile param string $phpOriginalFile (string)

Method setColor()

It sets the color in the stack

Parameters:

• $colors =['red','yellow','green','white','blue','black',cyan','magenta'][$i] (array)

Method setParam()

It sets the value or value-key of a parameter manually.
It also marks the origin of the argument as "set" and it markes the argument as missing=false

Parameters:

• $key the key of the parameter (string)
• $value the value (or the value-key) to assign. (mixed)
• $isValueKey if false (default) then the argument $value is the value of the parameter
  if true then the argument $value is the value-key. (bool)
• $createIfNotExist If true and the parameter doesn't exist, then it is created with the default configuration. (bool)

Method setParamUsingArray()

Set the values of the parameters using an array.
If the parameter does not exist, then it is created with the default values

Parameters:

• $assocArray An associative array of the form ['key'=>'value'] (array|null)
• $fields if null, then is set all values of the array
  If not null, then it is used to determine which fields will be used (array|null)

Method createContainer()

USE FUTURE. It creates a container.

Parameters:

• $width param $width ()
• $height param $height ()

Method getValueAsArray()

It gets the values of the parameters are an associative array.

Parameters:

• $fields If the fields are null then it returns all parameters, including "none". (array|null)
• $asAssocArray (def:true) if true then it returns the values as an associative array
  if false, then it returns as an indexed array. (bool)

Method setPatternTitle()

It sets the pattern used for the title. This operation is used in a stack. {value} {type}

Parameters:

• $pattern1Stack if null then it will use the default value. (?string)

Method setPatternCurrent()

Parameters:

• $pattern2Stack if null then it will use the default value. (?string)

Method setPatternSeparator()

">"

Parameters:

• $pattern3Stack if null then it will use the default value. (?string)

Method setPatternContent()

Not used yet.

Parameters:

• $pattern4Stack if null then it will use the default value. (?string)

Method setStyle()

It sets the styles used by different elements

Parameters:

• $style =['mysql','simple','double','minimal','style'][$i] (string)
• $waitingIconStyle =['triangle','braille','pipe','braille2','bar','bar2','bar3','arc','waiting'][$i]
  if is an array, then it uses the elements of array to show the waiting icon (string|array)

Method show()

It's similar to showLine, but it keeps in the current line.

Parameters:

• $content param string $content (string)
• $stream =['stdout','stderr','memory'][$i] (?string)

Method showBread()

It shows a breadcrumb.
To add values you could use the method uplevel()
To remove a value (going down a level) you could use the method downlevel()
You can also change the style using setPattern1(),setPattern2(),setPattern3()

It shows the current BreadCrumb if any.

Parameters:

• $showIfEmpty if true then it shows the breadcrumb even if it is empty (empty line)
  if false (default) then it doesn't show the breadcrumb if it is empty. (bool)

Method showCheck()

It shows a label messages in a single line, example: [ERROR] Error message

Parameters:

• $label param string|array $label (string|array)
• $color =['red','yellow','green','white','blue','black',cyan','magenta'][$i] (string)
• $content param string|array $content (string|array)
• $stream =['stdout','stderr','memory'][$i] (string)

Method showFrame()

It shows a border frame.

Parameters:

• $lines the content. (string|string[])
• $titles if null then no title. (string|string[]|null)

Method showLine()

It shows (echo) a colored line. The syntax of the color is similar to html as follows:
Example:

Parameters:

• $content content to display (string|string[])
• $cliOneParam param ?CliOneParam $cliOneParam (?CliOneParam)
• $stream =['stdout','stderr','memory'][$i] (?string)

Method clearScreen()

It clears the current screen
Example:

Method cursorHome()

It sets the cursor to the top left position
Example:

Method cursorMove()

It moves the cursor at some specific position
Example:

Parameters:

• $type=['up','upmost','down','downmost','right','rightmost','left','leftmost','pos'][$i]
  
• up : it moves the cursor up "n" parameter
  
• down : it moves the cursor down "n" parameter
  
• right : it moves the cursor right "n" parameter
  
• left : it moves the cursor left "n" parameter
  
• upmost : it moves the cursor to the upper minus "n"
  
• downmost : it moves the cursor to the down minus "n"
  
• rightmost : it moves the cursor to the rightmost minus "n"
  
• leftmost : it moves the cursor to the leftmost minus "n"
  
• pos : it moves the cursor to the [x,y] parameter
  (string)
• $parameter param mixed $parameter (mixed)

Method bell()

Method getCursorPosition()

It gets the current position of the cursor

It requires getCh() executable up and configured in Windows Example:

Method showMessageBox()

It shows a message box consisting of two columns.

Parameters:

• $lines (right side) (string|string[])
• $titles (left side) (string|string[])
• $wrapLines if true, then $lines could be wrapped (if the lines are too long) (bool)

Method alignLinesVertically()

Parameters:

• $lines The lines to align (string[])
• $numberLines the number of lines vertically to use to align the text. (int)
• $align =['middle','top','bottom'][$i] (string)

Method maxWidth()

Method showParamSyntax()

It shows the syntax of a parameter.

Parameters:

• $key the key to show. "*" means all keys. (string)
• $tab the first separation. Values are between 0 and 5. (int)
• $tab2 the second separation. Values are between 0 and 5. (int)
• $excludeKey the keys to exclude. It must be an indexed array with the keys to skip. (array)

Method showParamSyntax2()

It shows the syntax of the parameters.

Parameters:

• $title A title (optional) (?string)
• $typeParam =['command','first','last','second','flag','longflag','onlyinput','none'][$i] the type of parameter (array)
• $excludeKey the keys to exclude (array)
• $includeKeys the whitelist of elements that only could be included.
  Only keys that are in this list are added. (array|null)
• $related if not null then it only shows all the parameteres that are related.
  use $param->setRelated() to set the relation. (string|null)
• $size the minimum size of the first column (?int)

Method setDefaultStream()

Parameters:

• $stream =['stdout','stderr','memory'][$i] (string)

Method setNoColor()

Parameters:

• $noColor if true then it will not show colors
  if false, then it will show the colors. (bool)

Method isNoColor()

Method setNoANSI()

if true then the console is in old-cmd mode (no colors, no utf-8 characters, etc.)

Parameters:

• $noANSI param bool $noANSI (bool)

Method isNoANSI()

returns true if the

Method wrapLine()

it wraps a line and returns one or multiples lines
The lines wrapped does not open or close tags.

Parameters:

• $texts The text already formatted. (string|array)
• $width The expected width (int)
• $keepStyle if true then it keeps the initial and end style tag for every new line.
  if false, then it just wraps the lines. (bool)

Method showProgressBar()

Parameters:

• $currentValue the current value (numeric)
• $max the max value to fill the bar. (numeric)
• $columnWidth the size of the bar (in columns) (int)
• $currentValueText the current value to display at the left.
  if null then it will show the current value (with a space in between) (?string)

Method getPageSize()

it gets the size of the page (number of rows) to display in a table

Method showTable()

It shows an associative array. This command is the end of a stack.

Parameters:

• $assocArray An associative array with the values to show. The key is used for the index. (array)
• $notop if true then it will not show the top border (bool)
• $nosides if true then it will not show the side borders (bool)
• $nobottom if true then it will not show the bottom border (bool)
• $maxColumns The max number of columns to show.
  If the table has 15 columns and maxColumns is 5, then only the first 5 columns will be displayed. (int)
• $reduceRows The number of rows to reduce considering the size of the screen.
  If the screen has 30 rows, then the table will use 30-3=27 rows
  If set to >-99999, then it will display all rows. (int)
• $curpage The number of page (base 1) to display. (int)

Method showValuesColumn()

It shows the values as columns.

Parameters:

• $values the values to show. It could be an associative array or an indexed array. (array)
• $type ['multiple','multiple2','multiple3','multiple4','option','option2','option3','option4'][$i] (string)
• $patternColumn the pattern to be used, example: "[{key}] {value}" (?string)

Method showWaitCursor()

It shows a waiting cursor.
Example:

Parameters:

• $init the first time this method is called, you must set this value as true. Then, every update must be false. (bool)
• $postfixValue if you want to set a profix value such as percentage, advance, etc. (string)

Method hideWaitCursor()

Method hideCursor()

Method showCursor()

Method showparams()

It will show all the parameters by showing the key, the default value and the value
It is used for debugging and testing.

Method showParamValue()

Parameters:

• $parameter param CliOneParam $parameter (CliOneParam)

Method strlen()

It determines the size of a string

Parameters:

• $content param $content ()
• $visual visual means that it considers the visual lenght, false means it considers characters. (bool)

Method removechar()

remove visible characters at the end of the string. It ignores invisible (such as colors) characters.

Parameters:

• $content param string $content (string)
• $numchar param int $numchar (int)

Method upLevel()

Up a level in the breadcrumb

Parameters:

• $content the content of the new line (string)
• $type the type of the content (optional) (string)

Method getCh()

It reads an input character. It does not work with special characters
This function is basic, it does not work with all keystrokes, and it could be CPU intensive (for a loop)

In Windows, it uses the getch.exe in any path folder (or you can set the path with $this->getChWinExe).
You can download from here https://github.com/escuelainformatica/getch/releases Example:

Parameters:

• $waitUntilKeyPress if true (default), it waits until a key is pressed (bool)
• $asNumber if true (default), returns the result as a two byte integer. (bool)

Method colorText()

It sets the color of the cli

Parameters:

• $content param string $content (string)
• $cliOneParam param ?CliOneParam $cliOneParam (?CliOneParam)

Method colorLess()

It removes all the escape characters of a content

Parameters:

• $content param string $content (string)

Method colorMask()

It masks (with a char 250) all the escape characters.

Parameters:

• $content param $content ()

Method initialEndStyle()

It returns the initial and end style of a text.
If the text only contains an initial or final style, then nothing is returned

Parameters:

• $contentAnsi the content text already formatted in Ansi (string)
• $initial (this value is returned) (?string)
• $end (this value is returned) (?string)

Method replaceCurlyVariable()

Replaces all variables defined between {{ }} by a variable inside the dictionary of values.
Example:

Parameters:

• $string The input value. It could contain variables defined as {{namevar}} (string)
• $notFoundThenKeep [false] If true and the value is not found, then it keeps the value. Otherwise, it is replaced by an empty value (bool)

menu

You can create a menu using the next methods

addMenu()

It creates a new menu

addMenuItem()

It adds an option to a menu

addMenuItems()

It adds multiple options to a menu

evalMenu()

It executes a menu

clearMenu()

It clears a menu.

example

Examples

Example using arguments

example/example1.php

And create the next code

So you can run as:

Example using user input

You can ask for user input of the user.

example/example2.php

It will show the next result

Example with a game

example/examplegame.php

Image (c) George Beker

Example colors

You can see the tags available in Types of colors

example/examplecolor.php

Example tables

example/exampletables.php

Types of user input

Types of colors

Definitions

You can find the definition of the classes, methods and fields at:

definitions.md

debug

To activate the debug mode, you must set the debug field as true:

In debug mode, every user input is recored in the field $debugHistory

You can also see the history running the input ??history

And you can clear the history using the input ??clear

The goal is we could store a session and replace it using testUserInput()

You can also load and save the user input

• ??history it shows the history
• ??clear it clears the history
• ??load it load the user input and runs it.
• ??save it saves the user input in a file called _save.json
• ??load:file ??save:file you can also specify the filename where it will be saved

Compatibility

• It must support all moderns interface that are compatibles with Virtual Terminal.
• Since Windows TH2 (v1511, 2015), cmd.exe and powershell.exe has supports or VT, but it must be enabled.
  • REG ADD HKCU\CONSOLE /f /v VirtualTerminalLevel /t REG_DWORD /d 1
• Since Windows 10 Anniversary Edition (v1607, 2016), cmd.exe and powershell.exe has default supports of VT (AFAIK)
• Windows 2019 (LTS, 2018) supports this library by default.
• Windows Terminal supports all features.
• The screen size width is -1 column less in older version of Windows. C'mon, Microsoft!

Changelog

• 1.35 (2024-09-23)
  • new method clearScreen()
  • new method cursorHome()
  • new method cursorMove()
  • new method bell()
  • new method getCursorPosition()
  • fixed fixed some comments.
• 1.34 (2024-09-20)
  • fixed a couple of bugs in showTable().
  • fixed comments in the code
• 1.33 (2024-08-02)
  • json_encode does not throw an exception. Now it fails with empty or default value.
• 1.32.1 (2024-03-02)
  • fixed some fields, default values and type hinting.
• 1.32 (2024-03-02)
  • Updating dependency to PHP 7.4. The extended support of PHP 7.2 ended 3 years ago.
  • Added more type hinting in the code.
• 1.31 (23-09-02)
  • new methods:
  • hideCursor()
  • showCursor()
  • modified method:
  • setStyle() now allows two arguments.
• 1.30 (23-09-02)
  • Best identification of the version of Windows. 10.1607 and higher is considered compatible.
  • Fixed: scroll and wait cursor now work correctly.
  • Preliminary Container.
• 1.29.1 (23-04-06)
  • Fixed a bug with addMenuService()
• 1.29 (23-04-06)
  • In the debug mode, you can ??load, ??save the operations.
• 1.28 (2023-04-05)
  • the $debug field, so you can debug and store the user input history.
  • PHP_FAKE_READLINE constant or global variable now is a static field $fakeReadLine
• 1.27 (2023-04-02)
  • new method instance() so you can get or create a new singleton instance.
  • new method hasInstance()
  • new method hasMenu()
  • new method addMenuService()
  • fixed a bug with showHelp() and the help is an array or the help is missing.
• 1.26.1 (2023-03-21)
  • cleaned some code.
• 1.26 (2023-03-21)
  • addMenu() and addMenuItem() allow to use callable arguments.
• 1.25.1 (2023-03-20)
  • Fixed a small bug with evalMenu()
  • Added option to addMenu() ($size)
• 1.25 (2023-03-20)
  • Added method clearMenu(),addMenu(),addMenuItem(),addMenuItems(),evalMenu()
  • Added method setVariable(),getVariable() and addVariableCallBack(). $variable field is now private.
• 1.24 (2023-03-11)
  • Added new method createOrReplaceParam(),setParamUsingArray(),getValueAsArray()
  • setParam() has a new argument to create the parameter if it is not defined.
  • Added variables that could be displayed when the text contains "{{namevar}}"
• 1.23 (2023-03-05)
  • Added new methods readDataPHPFormat() and saveDataPHPFormat()
  • readDate() and saveData() generate a file that includes the version and the date of generation. It does not impact older files.
• 1.22.3 (2023-03-04)
  • fixed a small bug when some value is null. It could throw a warning in PHP
• 1.22.2 (2023-02-17)
  • some cleanups
• 1.22.1 (2022-7-30)
  • fix a small typo in the code.
• 1.22 (2022-07-30)
  • setInput() added format wide to use 1 column (if the screen is equal or less than 80 columns) or two columns
  • "option" ignore cases.
• 1.21 (2022-06-27)
  • showMessageBox() now support colors and line carriage.
• 1.20 (2022-06-21)
  • showMessageBox() added wrap lines
  • updated the way to find if an array is associative or not.
• 1.19 (2022-06-18)
  • Update the creation of table
• 1.18.1 (2022-06-17)
  • Fixed a bug when we use setCurrentAsDefault() but the type of value is an option (we set the default the valuekey instead of the value)
• 1.18 (2022-06-11)
  • Added the method addExtensionFile()
• 1.17 (2022-06-09)
  • fixed many problems with Linux (number of rows, autocomplete, etc.)
• 1.16 (2022-03-25)
  • setParam() allows to set the value or the value-key
• 1.15 (2022-03-15)
  • showHelp() shows more information.
  • colorText() now correct some missing tags.
• 1.14 (2022-03-04)
  • method showTable() allows to show or hide the top, sides and bottom borders.
• 1.13 (2022-02-28)
  • Changed silentError to errorType
• 1.12 (2022-02-26)
  • CliOne:
    • added a memory stream
    • set the default stream
    • set the current stream to use stdout,stderr or memory (stdin is not used for in)
    • added a new parameter type "command" that it is equals than first, but it ignores the name and considers the position.
    • added the method showHelp()
    • added the method makeBigWords()
    • added fontZnaki()
    • added fontaatr()
      • both fonts use a lot of space in code, but they are only an array of bits, so they use only 2KB.
    • new method alignLinesVertically()
    • new method maxWidth()
    • renamed field cmdMode to noANSI
    • method initialEndStyle()
  • CliOneParam:
    • Added a field related.
• 1.11 (2022-02-22)
  • Added supports for STDIN, STDOUT, and STDERR.

• 1.10 (2022-02-21)

  • [new] support for the old command line (cmd.exe). It is activated automatically.
    • It degraded the colors to b&w and changes the utf-8 characters to be compatible.
    • Also, the scroll bar and the waiting cursor is not displayed in this mode.
    • See compatibility for more information.
• 1.9 (2022-02-20)
  • [new] argumentIsValueKey and memory
  • [changed] Changed the signature of createParam(), switched the second and third argument
• 1.8 (2022-02-20)
  • [new] setParam() throw an exception if the parameter is not defined.
  • [new] showParamSyntax2()
  • [new] CliOneParam::$nameArg name of the argument (used in help)
• 1.7 (2022-02-18)
  • [fix] added type hinting for most fields and methods.
  • [new] new setValue() for CliOneParam.
• 1.6.1 (2022-02-18)
  • [fix] fixed a small bug with the value is set manually, so it is still marked as missing.
• 1.6 (2022-02-18)
  • [new] new method isParameterPresent()
• 1.5.5 (2022-02-18)
  • getParameter() always returns a parameter, no matter if it does not exist.
    • You can use the method isValid() to check its validity
  • setSilentError() you can silent the error output.
  • addhistory() renamed as setAddHistory()
  • To add a new parameter add() validates if the key is already in use, if the key is an alias of other, or if the alias is in use.
• 1.5.4 (2022-02-18)
  • fixed a problem with the default value.
  • added history (if available)
• 1.5.3 (2022-02-18)
  • nothing, just a renumeration
• 1.5.2 (2022-02-18)
  • [fix] some cleanups of the code.
• 1.5.1 (2022-02-18)
  • [fix] fixed a problem when the type is "none", it returned null instead of false.
  • [new] CliOneParam::evalParam() could return the value instead of the instance.
• 1.5 (2022-02-17)
  • [fix] corrected the display and trim of some text when the text uses a color.
  • [new] it allows multiples types of arguments (not only flags), including positional, flags, long-flags are none.
  • [new] added stack. Some visual elements allows to stack values.
• 1.4.1 (2022-02-15)
  • [fix] some fix for characters thare unicode. The system will use automatically MB_STRING if the library is available. Otherwise, it will use the default library
  • [new] new styles and patterns for components.
• 1.4 (2022-02-15)
  • [replaced] now all colors are express not abbreviated "" => "", etc.
  • [new] added all basic colors, background and solved a problem with the underline.
  • [new] added showFrame(),showTable(),showWaitCursor(),showProgressBar()
• 1.3 (2022-02-14)
  • [new] added autocomplete (tab key)
  • [new] added breadcrub
  • [new] added showValuesColumn()
  • [replaced] now keys (showing in options) are aligned at the center.
• 1.2.2 (2022-02-14)
  • [fixed] fixed a problem where the question is truncated with an ellipsis (...)
• 1.2.1 (2022-02-13)
  • [fixed] fixed some bugs
  • [new] keys are padded, example /[ 1] /[ 2] /[ 3] ... [99], /[value 1] /[value 2] /[value ]
• 1.2 (2022-02-13)
  • [replaced] "options" renamed as "multiple". Added "multiple2","multiple3","multiple4"
  • [new] associative arrays are allowed.
  • [new] added templates.
  • [new] added valuekey.
• 1.1 (2022-02-12)
  • [new] new methods savedata(),getArrayParams(),setArrayParam(),readData()
  • [replaced] a new argument for the method replaceColor()
  • [new] a new type called password
• 1.0.1 (2022-02-11)
  • [Fixed] namespace.
  • [Fixed] replaceColor() fixed a color
  • [Added] CliOne::indVendorPath()
• 1.0 (2022-02-11)
  • End of beta, first release.
• 0.7 (2022-02-11)
  • Added option4.
  • optionshorts allows to specify the first letter, only if the first letter is unique, examples: yes/no allows to use y/n
• 0.6 (2022-02-11)
  • Added option2 and option3
  • allowNulls() now doesn't work with default values.
• 0.5 (2022-02-03)
  • [unittest] Better unit test.
  • [CliOneParam] You can set if you allow empty values or not.
  • [CliOne] You can set if you allow empty values or not.
• 0.4 (2022-01-27) Now test coverage is over the 75%
• 0.3 (2022-01-26) new corrections to the reading of values
• 0.2 some updates
• 0.1 first version