Ian's Random Bits of Information

I found myself in another familiar time where I needed a PHP class and didn’t want to re-invent the wheel. Initial searches for PHP ANSI terminal coloring either resulted in snippets, or classes that didn’t fit the par.

Thankfully, I can always turn to the wonderful perl repository CPAN. Being native to perl, it is very convenient to have this resource either for great ideas or direct ports. This time its going to be a direct port (with minor modifications) of a module I’m already familiar with: Term::ANSIColor.

ANSIColor.php (requires 5.3+)

I’ve taken the liberty of porting the documentation as needed, so I must give much credit to Russ Allberry.
All the methods of Term::ANSIColor have been ported over to this class, with the exception of the color stack methods (PUSHCOLOR, POPCOLOR, and LOCALCOLOR). Of course, some minor modifications have been made to make it optimal for PHP. One main modification is the missing functionality of automagically updating stdout. Personally, I like to have more control and don’t want to have to worry about resetting attributes/values between outputs (please tell me if you think I’m wrong).

While the supported colors remains the same, the names of the colors have changed (reasoning for this will come later):

The bright and on attribute types of TERM::ANSIColor (bright_black,on_black…) have changed. All the attributes are lower case with NO underscores (yeah, it looks a little ugly but just wait for the reason):

For example (perl => php):

• bright_black => brightblack
• on_black => onblack
• on_bright_magenta => onbrightmagenta

The rest of the attributes can be found at the beginning of the class.

The other major modification is the constant interface. The constant interface has been changed, so in the perl version:

print BOLD BLUE "Text\n";

Is now, in the PHP version:

$ac = new ANSIColor();
echo $ac->bold_blue("Text\n");

Or:

<pre>$ac = new ANSIColor();
echo $ac->Bold_Blue("Text\n");</pre>

In other words, the constant interface is now a dynamic method interface. I do plan to add more 5.3 goodness with __callStatic.

This dynamic method interface is the reason for the change in the attribute naming convention with using underscores. I did test other ways of doing this, but it just seemed like too much overhead.

Enough of the big modifications and lets continue with the ported methods:

color

Original (perl):

color(ATTR[, ATTR ...]);

Ported (PHP)

$ac = new ANSIColor();
$ac->color(array('ATTR','ATTR'...));

color() takes an array of attributes. It then forms and returns the escape sequence to set those attributes. It doesn’t print it out, just returns it, so you’ll have to print it yourself if you want to. This is so that you can save it as a string, pass it to something else, send it to a file handle, or do anything else with it that you might care to. color() throws an exception if given an invalid attribute.

colored

Original (perl):

colored(ATTR-REF, STRING[, STRING...]);

Ported (PHP)

$ac = new ANSIColor();
$ac->colored(ATTR-REF,array('STRING','STRING'...));

colored() takes a scalar as the first argument and an array of attribute strings as the second argument and returns the scalar wrapped in escape codes so that the attributes will be set as
requested.

Normally, colored() just puts attribute codes at the beginning and end of the string, but if you set $ac->EACHLINE to some string, that string will be considered the line delimiter and the attribute will be set at the beginning of each line of the passed string and reset at the end of each line. This is often desirable if the output contains newlines and you’re using background colors, since a background color that persists across a newline is often interpreted by the terminal as providing the default background color for the next line. Programs like pagers can also be confused by attributes that span lines. Normally you’ll want to set $ac->EACHLINE to “\n” to use this feature.

uncolor

Original (per):

uncolor(ESCAPE);

Ported (PHP):

$ac = new ANSIColor();
$ac->uncolor(ESCAPE);

PHP Example:

$ac = new ANSIColor();
$ac->uncolor(array('1;42', chr(27) . "[m", '', chr(27) . "[0m")); // array('bold','ongreen','reset')

uncolor() performs the opposite translation as color(), turning escape sequences into a list of strings corresponding to the attributes being set by those sequences.

colorstrip

Original (perl):

colorstrip(STRING[, STRING ...]);

Ported (PHP):

$ac = new ANSIColor();
$ac->colorstrip('STRING');

colorstrip() removes all color escape sequences from the provided string, returning the modified string.

colorvalid

Original (perl):

colorvalid(ATTR[, ATTR ...]);

Ported (PHP):

$ac = new ANSIColor();
$ac->colorvalid('ATTR');

colorvalid() takes one string the same type as color() and returns true

That wraps up this port, if you feel like I butchered this port or have any comments/questions please let me know.

PS. Sorry for the 5.3 requirement, if you want me to post an alternate version let me know… otherwise you’ll “mainly” have to update the colored method.

~ by ityndall on October 12, 2010.

Posted in PHP