PHP port of Term::ANSIColor

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.

16 Responses to “PHP port of Term::ANSIColor”

  1. Nice site, nice and easy on the eyes and great content too.

  2. Really nice post,thank you

  3. pretty helpful material, overall I consider this is well worth a bookmark, thanks

  4. hello!This was a really terrific topic!
    I come from roma, I was fortunate to search your website in google
    Also I learn much in your subject really thank your very much i will come every day

  5. It’s really a nice and helpful piece of information. I’m glad that you shared this helpful info with us. Please keep us informed like this. Thanks for sharing.

  6. hi!This was a really outstanding subject!
    I come from roma, I was fortunate to seek your subject in baidu
    Also I obtain much in your theme really thanks very much i will come daily

  7. Thanks for the post, keep posting stuff

  8. Terrific work! This is the type of information that should be shared around the web. Shame on the search engines for not positioning this post higher!

  9. Beneficial info and excellent design you got here! I want to thank you for sharing your ideas and putting the time into the stuff you publish! Great work!

  10. Thanks for the post, keep posting stuff

  11. great experience, dude! thanks for this great post wow… it’s very wonderful report.

  12. Great information! I’ve been looking for something like this for a while now. Thanks!

  13. Pretty nice post. I just stumbled upon your blog and wanted to say that I have really enjoyed browsing your blog posts. In any case I’ll be subscribing to your feed and I hope you write again soon!

  14. Hey I think you have a great blog going here, I found it on Bing and plan on returning regularly for the information that you all are providing.

  15. Thanks for the great post. Page Bookmarked

  16. Thanks for the great post. Page Bookmarked

Leave a Reply