PHPackages                             diqa/formatter - 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. diqa/formatter

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

diqa/formatter
==============

CLI formatting library

1.2(8mo ago)13511GPL-2.0-or-laterPHPPHP >=7.2.0

Since Dec 5Pushed 8mo ago1 watchersCompare

[ Source](https://github.com/kkthek/diqa-formatter)[ Packagist](https://packagist.org/packages/diqa/formatter)[ Docs](https://www.diqa.de/)[ RSS](/packages/diqa-formatter/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (2)Versions (7)Used By (1)

README
======

[](#readme)

The formatting library `diqa/formatter` eases formatted text output in multiple columns on the console.

Features:

- Fixed column sizes
- Different alignments inside the columns
- Separators (horizontal lines)
- Border support
- Padding
- Color highlighting (for console)
- Word wrapping or shortening
- Char sequences can be ignored by layout mechanism

Quick start
-----------

[](#quick-start)

First, you have to initialize the formatter with a configuration.

The only required option for the config object is the first parameter: **column width**. All others are optional. In the given example we have a 3-column layout with left alignment for the first column, center alignment for the second and right alignment for the 3rd. We also opted-in borderPadding.

```
$config = new Config([20,30,20],
 [Config::LEFT_ALIGN, Config::CENTER_ALIGN, Config::RIGHT_ALIGN],
 [
  'borderPadding' => true
 ]
);

$formatter = new Formatter($config);

```

Now you can use it. You either print one row or an array of rows.\[1\]

One row:

```
$output = $formatter->formatLine("column1", "column2", "column3");

```

Multiple rows:

```
$output = $formatter->format([
 ["column1", "column2", "column3"],   // row 1
 ["column1", "column2", "column3"],   // row 2
 ["column1", "column2", "column3"]    // row 3
]);

```

Options
-------

[](#options)

The config class has the following constructor parameters:

- array of **column widths** in characters, e.g. for 3 columns: `[ 20, 30 ,20 ]`
- array of **alignments** (optional, if missing LEFT\_ALIGN is default for all columns)

    - `Config::LEFT_ALIGN`
    - `Config::RIGHT_ALIGN`
    - `Config::CENTER_ALIGN`
    - `Config::LEFT_AND_RIGHT_ALIGN`
- array of options. The following are currently available:

    - **borderPadding**: Adds 1-char-padding at the borders (left and right). Default is none.
    - **border**: Adds a border \[2\]. Default is none.
    - **paddingChar**: Changes the padding character. default is a whitespace.
    - **wrapColumns**: Specifies if lines should be wrapped or shortened. Default is wrapped.
- Separator lines: A line can be one of the constants (holds for all columns)

    - `Config::LINE_SEPARATOR`: Renders a single line
    - `Config::DOUBLE_LINE_SEPARATOR`: Renders a double line
    - `Config::EMPTY_LINE_SEPARATOR`: Renders an empty line

    ```
    $output = $formatter->format([
     ["column1", "column2", "column3"],   // row 1
     [Config::DOUBLE_LINE_SEPARATOR],     // row 2
     ["column1", "column2", "column3"]    // row 3
    ]);

    ```

Additionally, the following methods are available:

- `highlightWord ($word, $color, $column = NULL)`

    - Highlights a word with a color. The last parameter is optional. If missing, the word is highlighted in all columns. See this example:

        ```
        $warningColor = Color::fromColor(Color::LIGHT_GREY, Color::RED);
        $config->highlightWord("[ERROR]", $warningColor, 3);

        ```

        Highlights the string "\[ERROR\]" in 3rd column with red background and lightgrey text color.
- `setSequencesToIgnore (array $sequences)`

    - Specifies character sequences which should be completely ignored by layouting mechanism. This is useful when you want to output formatting data for a printer for example. See this example:

        ```
        $config->setSequencesToIgnore(["//BOLD", "//ITALIC", "//OFF"]);

        ```

        These strings are completely ignored by the layout, for example "//BOLDHaus//OFF" is regarded as if it would be "Haus" only
- `setLeftColumnPadding(int $column, int $leftPadding)`

    - Specifies how much left-padding is applied on $column

Alignments
==========

[](#alignments)

While left, center and right alignments are quite self-explanatory, left-right alignment might not be. It means that a single column consists of two parts. First part is aligned left, second right. Example:

```
Date of purchase..................2020-07-12
Shop.......................Aldi Süd Oststadt
Product..Tütensuppe Miraculi Familienpackung

```

You cannot use a two column layout for this because in 1st row the first column overlaps the second column in the 3rd row.

Columns consisting of two parts are entered as arrays with two entries. So be careful: There are 3 arrays nesting. first is the rows, second the columns (actually only one here) and 3rd is the columns consisting of two parts.

```
$output = $formatter->format([
[["Date of purchase", "2020-07-12" ]],                 // row 1
[["Shop", "Aldi Süd" ]],                               // row 2
[["Product", "Tütensuppe Miraculi Familienpackung" ]]  // row 3
]);

```

Remarks
-------

[](#remarks)

### Word wrapping

[](#word-wrapping)

The algorithm to break columns in multiple lines tries to preserve word boundaries. Only if it does not find any whitespaces in the column's text, it does hard line feeds at the last possible character.

Footnotes
---------

[](#footnotes)

\[1\] Please note that one input row does not necessarily output to one row. Text could be broken down into several lines to fit the column widths.

\[2\] Please note that it usually does not make sense to output a single line in this case because the border boundaries at top and bottom are added as well.

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance59

Moderate activity, may be stable

Popularity11

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 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.

###  Release Activity

Cadence

Every ~680 days

Total

3

Last Release

263d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/86754319732f713c884b9481baefe7c35f735593975542028dbaef1adabc017d?d=identicon)[kkthek](/maintainers/kkthek)

---

Top Contributors

[![kkthek](https://avatars.githubusercontent.com/u/1655904?v=4)](https://github.com/kkthek "kkthek (1 commits)")

---

Tags

cliformatting

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/diqa-formatter/health.svg)

```
[![Health](https://phpackages.com/badges/diqa-formatter/health.svg)](https://phpackages.com/packages/diqa-formatter)
```

###  Alternatives

[symfony/console

Eases the creation of beautiful and testable command line interfaces

9.8k1.1B11.3k](/packages/symfony-console)[nunomaduro/collision

Cli error handling for console/command-line PHP applications.

4.6k331.8M8.5k](/packages/nunomaduro-collision)[nunomaduro/termwind

It's like Tailwind CSS, but for the console.

2.5k239.8M286](/packages/nunomaduro-termwind)[wp-cli/wp-cli

WP-CLI framework

5.0k17.2M320](/packages/wp-cli-wp-cli)[wp-cli/php-cli-tools

Console utilities for PHP

68325.0M367](/packages/wp-cli-php-cli-tools)[kamisama/cake-resque

A CakePHP plugin for creating background jobs with Resque

157415.4k](/packages/kamisama-cake-resque)

PHPackages © 2026

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