README

1. Features

Bash Colorizer outputs strings to the bash terminal with specified colors and attributes.

Let's make your bash terminal full of colors!

use Macocci7\BashColorizer\Colorizer;

Colorizer::attributes(['italic'])
        ->foreground('#ffff00')
        ->background('#0000ff')
        ->echo('Hi, there!', PHP_EOL);

2. Contents

• 1. Features
• 2. Contents
• 3. Verified Terminals
• 4. Requirements
• 5. Installation
• 6. Usage
  • 6.1. Basic Usage
  • 6.2. Available Attributes
  • 6.3. Available Colors
• 7. Examples
• 8. LICENSE

3. Verified Terminals

• VSCode Terminal (VSCode 1.99.1 / Windows 11)
• Windows Terminal 1.22.10731.0

4. Requirements

• PHP 8.1 or later installed
• Composer v2 installed
• Bash v5 installed (or Zsh)

5. Installation

composer require macocci7/bash-colorizer

6. Usage

6.1. Basic Usage

• Import composer's autoload.php at first.

  <?php
  
  require_once __DIR__ . '/../vendor/autoload.php';

• Displaying messages:

  static calls:

  use Macocci7\BashColorizer\Colorizer;
  
  Colorizer::echo("Hi, there!");
  Colorizer::echo(" How's it going with you?", PHP_EOL);

  method chains:

  Colorizer::echo("Hi, there!");
      ->echo(" How's it going with you?", PHP_EOL);

  creating an instance:

  $colorizer = new Colorizer;
  $colorizer->echo("Hi, there!")
      ->echo(" How's it going with you?", PHP_EOL);

• Configuration:

  static call:

  $config = [
      'attributes' => ['italic', 'bold'],
      'foreground' => 'black',
      'background' => 'green',
  ];
  
  Colorizer::config($config);
  Colorizer::echo("Hi, there!");

  method chain:

  Colorizer::config($config)
      ->echo("Hi, there!");

  creating an instance:

  // several ways
  $colorizer = new Colorizer;
  $colorizer = new Colorizer($config);
  $colorizer = Colorizer::config($config);
  
  $colorizer->config($config)
      ->echo("Hi, there!")
      ->echo(" How's it going with you?", PHP_EOL);

• Setting attributes:

  Colorizer::attributes(['underline', 'strike'])
      ->echo("Hi, there!", PHP_EOL);

  See more: Available Attributes

• Setting foreground color:

  by name:

  Colorizer::foreground('green')
      ->echo("Hi, there!", PHP_EOL);

  by hex code:

  Colorizer::foreground('#ffcc00')  // or #fc0
      ->echo("Hi, there!", PHP_EOL);

  by number [0 - 255] (256 colors):

  Colorizer::foreground(2)
      ->echo("Hi, there!", PHP_EOL);

  by (RGB) array (24bit 16777216 colors):

  Colorizer::foreground([0, 255, 0])
      ->echo("Hi, there!", PHP_EOL);

  See more: Available Colors

• Setting background color:

  by name:

  Colorizer::background("red")
      ->echo("Hi, there!", PHP_EOL);

  by hex code:

  Colorizer::background("#ffcc00")  // or #fc0
      ->echo("Hi, there!", PHP_EOL);

  by number [0 - 255] (256 colors):

  Colorizer::background(1)
      ->echo("Hi, there!", PHP_EOL);

  by (RGB) array (24bit 16777216 colors):

  Colorizer::background([255, 0, 0])
      ->echo("Hi, there!", PHP_EOL);

  See more: Available Colors

• Equivalent to config():

  Colorizer::attributes(['double-underline', 'italic'])
      ->foreground("yellow")
      ->background("blue")
      ->echo("Hi, there!", PHP_EOL);

• Setting underline color:

  by hex code:

  Colorizer::underline("#ffcc00")  // or #fc0
      ->echo("Hi, there!", PHP_EOL);

  by number [0 - 255] (256 colors):

  Colorizer::underline(1)
      ->echo("Hi, there!", PHP_EOL);

  by (RGB) array (24bit 16777216 colors):

  Colorizer::underline([255, 0, 0])
      ->echo("Hi, there!", PHP_EOL);

  See more: Available Colors

• Returning colorized string:

  As an argument of echo:

  echo Colorizer::config($config)
      ->encode("Hi, there!") . PHP_EOL;

  This is also effective:

  echo sprintf(
      "%s: %s%s",
      $name,
      Colorizer::config($config)
          ->encode("Hi, there!"),
      PHP_EOL
  );

• Returning human readable encoded string:

  echo Colorizer::attributes(["bold"])
      ->background([255, 255, 0])
      ->foreground([0, 128, 255])
      ->readable('Hi, There!', PHP_EOL);

  This code outputs the following string:

  \033[1;38;2;0;128;255;48;2;255;255;0mHi, there!\033[m

  Running bash command echo with -e option on this string takes colorizing effect:

  bash-$ echo -e '\033[1;38;2;0;128;255;48;2;255;255;0mHi, there!\033[m'

6.2. Available Attributes

*1: No effect with faint
*2: Not fast (blinks at the same rate as blink)
*3: Unknown because the corresponding attribute has no effect
*4: Also effective against fast-blink
*5: Partially effective

e.g.) on VSCode Terminal (theme:Dark Modern)

See more: Select Graphic Rendition parameters | ANSI escape code | Wikipedia

6.3. Available Colors

• foreground/background color names:

  • black
  • red
  • green
  • yellow
  • blue
  • magenta
  • cyan
  • white
  • extended (no effect, only name)
  • default

  e.g.) on VSCode Terminal (theme:Dark Modern)

  Foregound Colors	Background Colors

• 256 colors [ 0 - 255 ]: foreground/background/underline

  e.g.) foreground colors on VSCode Terminal (theme:Dark Modern):

  

  e.g.) background colors on VSCode Terminal (theme:Dark Modern):

  

  e.g.) underline colors on VSCode Terminal (theme:Dark Modern):

  

• 24bit (16777216) colors:

  e.g.) foreground colors on VSCode Terminal (theme:Dark Modern):

  

  e.g.) background colors on VSCode Terminal (theme:Dark Modern):

  

  e.g.) underline colors on VSCode Terminal (theme:Dark Modern):

  

7. Examples

Example codes are in playground directory.

• colorizer.php
• attributes.php
• foreground.php
• background.php
• foreground_256colors.php
• foreground_24bitcolors.php
• background_256colors.php
• background_24bitcolors.php
• underline_256colors.php
• underline_24bitcolors.php
• readable.php
• converter.php

8. LICENSE

MIT

Copyright 2025 macocci7.