changelog.md

CliToolkit -> Changelog

This change log references the repository changes and releases, which respect semantic versioning.

v3.0.1

Patches

1. Adapted the codebase to work smoothly with PHP 8.5
   1. Updated PHPUnit: 12.1.0 -> 12.5.6
2. Added short descriptions to all EnvironmentConfig.php settings.
3. Improved docs a bit.

v3.0.0

Backward incompatibilities:

1. Fixed a possible bug when a parent config parameter value is replaced with a subcommand parameters' values in a request multi-dimensional array. Example: when adding list parameter to a main config, it's value was then replaced with list subcommand sub-request values.

   The fix became possible with adding a special prefix to a request array key connected to a subcommand request values sub-array. Such a prefix can not be added to a parameter or subcommand name without a configuration error, which makes such request key naming safe.

   If previously you could access magic subcommand request parameters from the main request by $request->getParams()['magic'], from now on you should be OK with the built-in handy method $request->getSubcommandRequest(), which does not require specifying a chosen subcommand name - it detects that name automatically.

   However, if you want to check for existence of a particular request (subcommand call) manually, from now on you should do it this way: $request->getParams()[CliRequest::SUBCOMMAND_PREFIX . 'magic'] (where magic is a subcommand name).

   • Added CliRequest::SUBCOMMAND_PREFIX for subcommand request key names.

2. cli-toolkit plain scripts are removed to be replaced with ScriptClassAbstract.php-based scripts and a launcher, run.php.

   1. CompletionScript.php now utilizes ScriptFileDetector.php, thus the search-related parameters were changed accordingly.

3. HelpGenerator::getSubcommandsBlock() is removed - replaced with list built-in subcommand.

4. CliRequest::getSubcommandRequest(): removed $subcommandName parameter, changed return type hint from string to ?string: now the method always returns the called subcommand's request object or null if there was no subcommand call.

5. CliRequestProcessor::$config became readonly - you can not edit it after passing to __construct().

6. Question.php:

   1. __construct() method became protected. Now create() static method is the only way to create an instance.
   2. QUESTION_POSTFIX constant is removed. Now the default value is set directly for $questionPostfix property.
   3. getInput() trims the input instead of getAnswerOrDefault() that utilizes the former.
   4. If possibleAnswers() are set without isCaseSensitive mode enabled, the answer returned by ask() method will contain one of original possible answers: if YES is expected as one of answers and you provide yes, ask() will return YES as your answer (not yes, as was done in a previous version).

7. HelpGenerator.php:

   1. Moved to its own subdirectory, updated the namespace.
   2. Removed getSubcommandsBlock() (so as "COMMANDS" block output from getFullHelp()) to replace it with list built-in subcommand functionality.
   3. Removed getBaseScriptName() obsolete method.
   4. Changed visibility from public to protected for methods getDescriptionBlock() and getUsagesBlock().
   5. Added the third, mandatory HelpFormatter parameter to getUsageForParseErrorException().
   6. getParamsBlock():
      1. Made non-static.
      2. Removed $formatter parameter.
      3. Changed visibility from public to protected.
   7. makeDefinitionList():
      1. Made non-static.
      2. Removed $formatter, the first parameter.
      3. The last parameter, string $title is changed into an array of HelpParameterDefinition.
      4. Padding improvement: option full names are padded to start at the same column, if there is at least one short name present.
   8. Made makeParamDescription non-static, removed $formatter parameter.
   9. Moved constants to EnvironmentConfig as its properties to ease changing of the corresponding settings:

      • PAD_LEFT_MAIN -> helpGeneratorPaddingLeftMain

      • PAD_LEFT_PARAM_DESCRIPTION -> helpGeneratorPaddingLeftParameterDescription

        The value is changed from 3 to 4.

      • USAGE_MAX_OPTIONS -> helpGeneratorUsageNonRequiredOptionsMax

8. TerminalFormatter::__construct() expects bool $isDisabled instead of int|resource $resource: now it is possible to instantiate a formatter object that applies (or not) formatting with guarantee.

   createForStdOut() and createForStdErr() work as usual (stream_isatty() call is moved in those methods).

9. Removed EnvironmentConfig::detectTopmostDirectoryPath() method - replaced its usage with Utils::detectTopmostProjectRootDirectory()

10. Renaming:

    1. Config::newSubcommand() first parameter $subcommandValue -> $subcommandName.
    2. BuilderInterface::newSubcommand() (so as BuilderAbstract and ConfigBuilder) first parameter $subcommandValue -> $subcommandName.
    3. Completion.php:
       1. executeAutocomplete() -> executeCompletion
       2. generateAutocompleteScript() -> generateCompletionCode()
    4. Config.php:
       1. OPTION_NAME_HELP -> PARAMETER_NAME_HELP
       2. OPTION_NAME_AUTOCOMPLETE_GENERATE -> PARAMETER_NAME_COMPLETION_GENERATE (its value parametizer-internal-autocomplete-generate -> parametizer-internal-completion-generate)
       3. OPTION_NAME_AUTOCOMPLETE_EXECUTE -> PARAMETER_NAME_COMPLETION_EXECUTE (its value parametizer-internal-autocomplete-execute -> parametizer-internal-completion-execute)

11. composer.json: the type is changed from project to library. Not sure if it should be treated as incompatibility, but let's note it here just in case.

New features

1. Removed "minimum 2 subcommands" constraint from Config::commitSubcommandSwitch().

2. ScriptClassAbstract.php as a basement for class-based Parametizer-powered scripts.

   1. EnvironmentConfig::detectBottommostDirectoryPath() now tries to detect the class' "child" location when possible. Otherwise backwards to a launched script location.

3. Subcommand names (Config::newSubcommand()) now support the colon (:) symbol. Main purpose - a separator for script classes sections.

4. Built-in subcommands: each script with a subcommand switch automatically provides you with help (ShowHelpPage.php) and list (ListSubcommands.php) built-in subcommands.

   1. Every subcommand switch goes with list as its default value.
   2. All built-in subcommands always utilize a parent EnvironmentConfig.php instance (from a parent Config.php).

5. ScriptFileDetector.php detects plain Parametizer-based scripts. The result is mainly used to compile a completion script by CompletionScript.php

6. ScriptClassDetector.php detects ScriptClassAbstract.php-based scripts. The result is mainly used as subcommands for ScriptClassLauncher.php (see below).

7. ScriptClassLauncher.php enables a ready-to-go mean to load and launch ScriptClassAbstract.php-based scripts.

   The launcher class includes ClearCache.php subcommand that is automatically added to a launcher's config, if a launcher's script detector enables caching and a cache file exists. The subcommand lets you delete the created cache file.

8. Added ConfigBuilder::shortDescription() - such manually set descriptions are not affected by the description shortener. Useful when environment settings are not optimal for all descriptions.

9. VariableBuilderAbstract.php:

   1. Added an optional $areHiddenForHelp parameter for allowedValues() method, defaults to false.
   2. Added a protected method setAllowedValues() for common internal operations with the allowed values list.

10. ParameterAbstract.php: added a protected property $areAllowedValuesHiddenFromHelp, a related getter method areAllowedValuesHiddenFromHelp(), and a related optional parameter $areHiddenFromHelp for allowedValues() method.

11. HelpGenerator.php:

    1. Modified makeParamDescription():
       • Utilizes $areAllowedValuesHiddenFromHelp parameter property and does not show the list of values if the flag is set to true.
       • For subcommands: replaces "Allowed values" actual list with a hint about detected subcommands count and a subcommand name to show all available subcommands.
    2. Added getScriptShortDescription() that returns a manual short description set in a config or a shortened full description (based on specified EnvironmentConfig object).
    3. Added the second, HelpFormatter parameter to __construct().

12. Added new setting for EnvironmentConfig.php:

    • helpGeneratorPaddingLeftMain
    • helpGeneratorPaddingLeftParameterDescription
    • helpGeneratorUsageNonRequiredOptionsMax

13. CliRequest.php:

    1. __construct() changes:
       1. $config parameter is made public (from protected).
       2. Added $parent parameter to access parent request (from a subcommand request).
    2. Added getRequestedSubcommandName() method.
    3. Added executeBuiltInSubcommandIfRequested() method for built-in subcommands automatic execution; the method is utilized by Parametizer::run().

14. Added CliRequestProcessor::parseSubcommandParameters() protected method to ease processing of the default subcommand name (subcommand switch value).

15. Added CliRequestProcessor::$isForCompletion readonly flag (settable in __construct()). The flag is used to stabilize completion output due to the default subcommand switch value.

16. Config.php:

    1. Added public getBuiltInSubcommandClassesBySubcommandNames() method and the related methods:
       • public getSubcommandSwitchName() - to get a subcommand switch parameter name if present in a config;
       • public getBuiltInSubcommandClass() - to get a subcommand fully qualified class name by a subcommand name;
       • public getBuiltInSubcommands() - to get the list of built-in subcommand configs by their names;
       • protected addBuiltInSubcommands() - an internal method to add built-in subcommands automatically to every script that contains a subcommand switch parameter.
    2. Added getArgumentsByNames() that has argument names as keys, while getArguments() still renders numeric keys.
    3. Added $shortDescription protected property, the setter shortDescription and the getter getShortDescription.

17. CliToolkitScriptAbstract.php as a basement for all tools/cli-toolkit scripts.

18. Formatters:

    1. Added HelpFormatter::invert().
    2. Added ScriptFormatter::note().

19. Question.php:

    1. Added askAway() static method to shorten code in case there is no need for answer validation or any other setup.
    2. Added $dieMessage parameter to Question::confirmOrDie() method - outputs a message (if provided) before interrupting script's execution.

20. Utils.php for various stuff used in different places and structurally not fitting into any other class.

21. GenerateMassTestScripts.php as a tool to test the performance and other "law of large numbers" cases, when a launcher includes lots of class scripts.

Patches

1. Question.php:

   1. validateAnswer() adds errorMessage only if it was filled in possibleAnswers().

      Also, the dot symbol is removed. So now it is possible to decide yourself if any stop symbol is needed. For instance, you may want to see something like this: Oops :( Possible answers: ..., so there is no dot after :(.

   2. Changed possibleAnswers() and answerValidatorPattern() default errorMessage to Invalid answer. (added a dot symbol) - because of the change mentioned above.

   3. Improved a bit exception messages when both a list of possible answers and a validation pattern are set.

2. VariableBuilderAbstract::ensureNotRequiredAndHasDefaultSimultaneously(): fixed a bit the exception message.
3. HelpGenerator::getParamsBlock(), options block sort improvement: as previously, options are grouped by isRequired() state (required options go first), but from now on each group is additionally sorted by names.

v2.1.0

New features

1. AutoloadDetector.php is added for init.php.

   Previously all built-in scripts (cli-toolkit) could not be launched without calling composer install additionally inside the library directory. And from now on your main project's vendor/autoload.php path should be detectable.

Patches

1. PHPUnit version is upgraded from ^10 to 12.1.0.

   From now on PHPUnit engine itself is not present in the library and should be installed and launched separately.

2. Test classes are auto-loaded only during actual test launches. E.g. if you accidentally use tests/utils/CliProcess in your production classes under 'dev' environment (when you call composer install without --no-dev option), you will get "Class 'XXX' not found in ..." error. Previously there was no error, until you install composer packages with --no-dev flag.

3. HelpGenerator.php:

   1. Fixed scripts main description block - stopped counting symbols in space-only lines. Previously it caused too much padding for descriptions with too short space-only lines.
   2. Improved subcommand help usage block - when --help is called for a subcommand, all manual usage lines include the whole path (subcommand names) starting from the topmost config.

v2.0.0

Backward incompatibilities:

1. PHP minimal required version is 8.3.
   1. Set explicitly types for all classes constants.
2. Config::createHelpOption() is deleted because not needed anymore (see the point below).
3. Parametizer::setExceptionHandlerForParsing() requires a CliRequestProcessor object, HelpGenerator::getUsageForParseErrorException() requires a Config object as the second parameter, CliRequestProcessor::__construct() is added with a required Config object parameter, CliRequestProcessor::load() signature is changed - Config object parameter is removed. This way it's possible to get an innermost branch config for ParseErrorException instances.
4. $isForStdErr parameter is removed from HelpGenerator::getUsageForParseErrorException(), the method always use a formatter for STDERR stream.
5. Parametizer::setExceptionHandlerForParsing() renders both an error message and a help block in STDERR (previously a help block was rendered in STDOUT).
6. Option::getOptionCleanFullName() is deleted because of no usage.
7. Renaming:
   1. CliRequest::getCommandRequest() -> getSubcommandRequest()
   2. CliRequestProcessor::getAllowedArguments() -> getInnermostBranchAllowedArguments()
   3. CliRequestProcessor::append() -> appendToInnermostBranch()
8. HelpGenerator::getUsageTemplate() is made protected (from public) and non-static. Then it's able to use an instance $formatter property (instead of creating a separate formatter instance).

New features

1. Added Environment Config that allows setting "environment"-related options like a short name for built-in --help option and short description boundaries. Other changes provoked by this addition:
   1. Config::__construct(), ConfigBuilder::__construct() and Parametizer::newConfig() support a new optional parameter $envConfig to pass EnvironmentConfig instance.
   2. Added Config::$envConfig protected property to keep EnvironmentConfig instance and the related getEnvConfig() public method.
2. CliRequest provides getParamAs* helper methods for easier parameters' values type casting, see Features Manual: Type casting from requests.
3. Added HelpGenerator::getShortDescription() that is used to show short versions for subcommand descriptions, when outputting a help page for a script with a list of available subcommands.

Patches

1. Added a paragraph about subcommands into Features Manual: Subcommands.
2. Formatted subcommand name in HelpGenerator::getUsageTemplate(), so subcommands would be more visible in the 'COMMANDS' section of a help page with a list of available subcommands.
3. Fixed completion for option short names in subcommands.
4. Made completion smarter: duplicate option and value mentioning is not completed.

v1.0.0

The first official release. Mainly focused on Cliff improvements and some additions like:

• more transparent and convenient config builder;
• generate-autocompletion-scripts.php (eases completion init);
• TerminalFormatter (helps format the improved generated help pages);
• Question (helps implement interactive scripts);
• PHPUnit for autotests plus more autotests.