PHPackages                             norse-blue/flow - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [CLI & Console](/categories/cli)
4. /
5. norse-blue/flow

ActiveLibrary[CLI & Console](/categories/cli)

norse-blue/flow
===============

PHP fluid command builder.

11[1 issues](https://github.com/norse-blue/php-flow/issues)PHPCI failing

Since Jan 27Pushed 7y ago1 watchersCompare

[ Source](https://github.com/norse-blue/php-flow)[ Packagist](https://packagist.org/packages/norse-blue/flow)[ RSS](/packages/norse-blue-flow/feed)WikiDiscussions master Synced 3d ago

READMEChangelogDependenciesVersions (1)Used By (0)

 [![Build Status](https://camo.githubusercontent.com/bff71aa788b4b11e480287559be0d4b23ae5009d33dd31a3d7b2287a179b6471/68747470733a2f2f696d672e736869656c64732e696f2f7472617669732f636f6d2f6e6f7273652d626c75652f666c6f772e737667)](https://travis-ci.org/norse-blue/flow) [![Quality Score](https://camo.githubusercontent.com/66260d3180f7a6da460827dbf80bba1edc93db7362ef267eb8d4efbe276582c4/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f672f6e6f7273652d626c75652f666c6f772e737667)](https://scrutinizer-ci.com/g/norse-blue/flow) [![Coverage](https://camo.githubusercontent.com/7066a0421701edaa8fe392d583185d4425127b0fb580932432b769a990d5d552/68747470733a2f2f696d672e736869656c64732e696f2f7363727574696e697a65722f636f7665726167652f672f6e6f7273652d626c75652f666c6f772e737667)](https://scrutinizer-ci.com/g/norse-blue/flow) [![Total Downloads](https://camo.githubusercontent.com/f12046dee2f8e6594962ef26e87483ff2334f5a3afcbff5dd7f1f33c23876a1f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6e6f7273652d626c75652f666c6f772e737667)](https://packagist.org/packages/norse-blue/flow) [![Latest Stable Version](https://camo.githubusercontent.com/89dec7d7a8f2ea3d00550ad5c953fe8b1141afd2bf2693a046b7ffab06993c0e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e6f7273652d626c75652f666c6f772e737667)](https://packagist.org/packages/norse-blue/flow) [![License](https://camo.githubusercontent.com/3284b1115214f62cd12f20685339f6cd72c59fdeca012189348ac6c5c3e33a7c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6e6f7273652d626c75652f666c6f772e737667)](https://packagist.org/packages/norse-blue/flow)

About
-----

[](#about)

Flow allows to create command classes that have a fluid interface to set its arguments and options values and get the executable string at the end. Example:

```
$cmd = new IdCommand();
$cmd->user('axel')->_g(true);
var_dump((string)$cmd);

// Output:
// string(10) "id -g axel"

```

Installation
------------

[](#installation)

### Requirements

[](#requirements)

This package requires the following to work correctly:

> - [PHP 7.3+](https://php.net/releases/)
> - [PHP JSON extension](https://php.net/manual/en/book.json.php)

Require Flow using [Composer](https://getcomposer.org):

```
composer require norse-blue/flow
```

Usage
-----

[](#usage)

There are two main ways to use this package, both methods are equivalent.

### Inheritance

[](#inheritance)

Create a new command class that inherits from `NorseBlue\Flow\Commands\FluidBaseCommand` and configure the arguments and options accordingly.

```
class IdCommand extends FluidBaseCommand
{
    protected $name = 'id';

    protected $arguments_definition = [
      'user' => ArgumentType::STRING,
    ];

    protected $options_definition = [
        '-a' => OptionType::BOOL,
        '-Z|--context' => OptionType::BOOL,
        '-g|--group' => OptionType::BOOL,
        '-G|--groups' => OptionType::BOOL,
        '-n|--name' => OptionType::BOOL,
        '-r|--real' => OptionType::BOOL,
        '-u|--user' => OptionType::BOOL,
        '-z|--zero' => OptionType::BOOL,
        '--help' => OptionType::BOOL,
        '--version' => OptionType::BOOL,
    ];
}
```

### Composition

[](#composition)

If you can't/won't use inheritance you can include the `NorseBlue\Flow\Commands\HandlesCommandInternals` trait to your class, configure the arguments and options accordingly and initialize the command anywhere (preferably in the constructor).

```
class IdCommand
{
    use NorseBlue\Flow\Commands\HandloesCommandInternals;

    protected $name = 'id';

    protected $arguments_definition = [
      'user' => ArgumentType::STRING,
    ];

    protected $options_definition = [
        '-a' => OptionType::BOOL,
        '-Z|--context' => OptionType::BOOL,
        '-g|--group' => OptionType::BOOL,
        '-G|--groups' => OptionType::BOOL,
        '-n|--name' => OptionType::BOOL,
        '-r|--real' => OptionType::BOOL,
        '-u|--user' => OptionType::BOOL,
        '-z|--zero' => OptionType::BOOL,
        '--help' => OptionType::BOOL,
        '--version' => OptionType::BOOL,
    ];

    public function __construct() {
        $this->init($this->arguments_definition ?? [], $this->options_definition ?? []);
    }
}
```

Command Configuration
---------------------

[](#command-configuration)

The command uses three properties to be configured: `name`, `arguments_definition` and `options_definition`.

### Name

[](#name)

This is the commands name. This will be prepended as-is to the resulting string. This name is the name of the command to be executed: `id`, `cat`, `git`, `composer`, etc.

### Arguments definition

[](#arguments-definition)

This is the definition array for the command arguments. The item's key is how the argument is identified and used for the command calls, e.g. a `'user'` entry creates a `user` method that can be called like `$cmd->user('value')`.

#### Array structure

[](#array-structure)

```
// Arguments definition
$arguments_defintiion = [
    {key} => {type},
];
/**
 * {key}: string argument identifier. It has to begin with a letter (either case) and can contain letters, numbers, underscore and dash. It cannot end in a dash. No spaces allowed
 * {type}: string or array. If a string is given then it has to be one of the ArgumentType enum values. If an array is given it has to match the argument spec structure.
 */

// Argument spec structure
$argument_spec = [
    'type' => {type},
    'validation' => {validation},
];
/**
 * {type}: string. One of the ArgumentType enum values.
 * {validation}: \Closure [optional]. A closure that validates the argument value when it is set.
 */
```

### Options definition

[](#options-definition)

This is the definition array for the command options. The item's key is how the option is identified and used for the command calls, e.g. a `'-g'` entry creates a `_g` method that can be called like `$cmd->_g(true)`.

**Notes:**

> - The dashes in key names are replaced with underscore when defining the method names. The definition still requires the use of dashes for the keys (as you would for the commands in a terminal).
> - [PHP function names are case-insensitive](https://php.net/manual/en/functions.user-defined.php), but this package makes the command method names case-sensitive, so `$cmd->_g(true)` and `$cmd->_G(true)` may or may not be equivalent (depending on the aliases in the definition).

#### Array structure

[](#array-structure-1)

```
// Options definition
$options_defintiion = [
    {key} => {type},
];
/**
 * {key}: string argument identifier. It must begin with '-' or '--' and a letter (either case). IT can contain letters, numbers, underscore, dash. It cannot end ina  dash. The option can have aliases separating them with '|', e.g. '-f|--flag'. No spaces allowed.
 * {type}: string or array. If a string is given then it has to be one of the OptionType enum values. If an array is given it has to match the option spec structure.
 */

// Option spec structure
$option_spec = [
    'type' => {type},
    'glue' => {glue},
    'validation' => {validation},
];
/**
 * {type}: string. One of the OptionType enum values.
 * {glue}: string [optional]. It is the string that glues the option identifier with its value when converting to string. Usually it does not need to be set. The default value is ' '.
 * {validation}: \Closure [optional]. A closure that validates the option value when it is set.
 */
```

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security
--------

[](#security)

If you discover any security-related issues, please email [security@norse.blue](axel.pardemann@norse.blue) instead of using the issue tracker.

License
-------

[](#license)

Flow is release under the [MIT license](LICENSE.md).

###  Health Score

14

—

LowBetter than 2% of packages

Maintenance0

Infrequent updates — may be unmaintained

Popularity3

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/61386558d4fa03cc9de21d20e76f396d5568e0e647e1cdf18f12c87f1a5f87b5?d=identicon)[axelitus](/maintainers/axelitus)

![](https://www.gravatar.com/avatar/848678ae5df09575d50a2817e573c114ab2255eeb9593b6c9de741fe4f8d0f64?d=identicon)[NorseBlue](/maintainers/NorseBlue)

---

Top Contributors

[![axelitus](https://avatars.githubusercontent.com/u/732441?v=4)](https://github.com/axelitus "axelitus (41 commits)")

### Embed Badge

![Health badge](/badges/norse-blue-flow/health.svg)

```
[![Health](https://phpackages.com/badges/norse-blue-flow/health.svg)](https://phpackages.com/packages/norse-blue-flow)
```

###  Alternatives

[wp-cli/wp-cli

WP-CLI framework

5.0k17.2M320](/packages/wp-cli-wp-cli)[consolidation/annotated-command

Initialize Symfony Console commands from annotated command class methods.

22569.8M19](/packages/consolidation-annotated-command)[chi-teck/drupal-code-generator

Drupal code generator

26947.8M5](/packages/chi-teck-drupal-code-generator)[seld/cli-prompt

Allows you to prompt for user input on the command line, and optionally hide the characters they type

24725.8M17](/packages/seld-cli-prompt)[illuminate/console

The Illuminate Console package.

12944.1M5.1k](/packages/illuminate-console)[php-tui/php-tui

Comprehensive TUI library heavily influenced by Ratatui

589747.0k6](/packages/php-tui-php-tui)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)