By: Stoyan Stefanov

April 11th, 2005

Reader Rating: 8.5

If you run a Website about programming, chances are that you display source code on your site's pages. Wouldn't it be great if the source code was highlighted -- displayed using different colors -- in the same way the desktop programming editors and IDEs display it? This would certainly make it much easier for your visitors to read the code.

This tutorial explains how you can highlight source code shown on your Website for a number of programming languages without manually formatting and hand-coding the display.

I'll show how to highlight source code in two ways:

1. Using the PHP's built-in highlighter for PHP source code


2. Using PEAR's Text_Highlighter package to highlight the source code for virtually any programming or markup language

This tutorial forms a sequel to my previous article, titled Use BB Code in Your PHP Application [1], and it uses the same setup for the code environment. While this article doesn't assume you've read the previous one, you might want to take a look at the Setup section of it.

Using PHP's Built-in Source Highlighter

PHP offer two functions for highlighting PHP code: highlight_file() [2] and highlight_string() [3]. Both functions return the same results, but each has its own specific input parameters. As their names suggest, the first function takes the filename of the PHP script whose code is to be highlighted, while the second takes the input as a string.

A Quick Example

Let's take a look at an example of the highlight_string() function in action:

<?php
include_once 'init.inc.php';

if (!empty($_POST['text'])){
   
   echo '<div style="border: solid 1px orange; padding: 20px; margin: 20px">';
   highlight_string($_POST['text']);
   echo '</div>';
}
?>

<form action="<?php echo $_SERVER['PHP_SELF']?>" method="post">
   <textarea name="text" style="width: 300px; height: 200px"><?php  
       echo @$_POST['text'];  
   ?></textarea>
   <br />
   <input type="submit" />
</form>

This script displays a simple textbox into which you can type or paste the PHP code you want to highlight. The code for the example is available in this article's code archive [4] and a live demo is available online [5]. The purpose of the init.inc.php file required at the beginning of the script was explained in the Setup section of my previous article [6].

Here's a screenshot of the script in action.

As you can see, the highlighted version of the code is much clearer and easier to follow than the standard black-and-white code.

Color Customization

The PHP highlighter uses the following colors to display the code:

The identifiers in the first column are actually the names of PHP configuration directives. This means that you can customize the highlight colors by altering the PHP configuration. So, if you want your keywords to be pink for a change (not pretty, I know, but this is just an example), you can do so by using a simple .htaccess file, containing:

php_value highlight.keyword #ff00ff

Drawbacks of the Native PHP Method

As you can see, this method of highlighting PHP source code is very easy to use, gives great results, and is customizable. However, it has some downsides:

• It will work properly on PHP source code only. Sometimes you can get somewhat acceptable results when highlighting other programming code, like HTML or JavaScript, but most times, the results won't be very good. This is simply because these highlight functions were designed specifically for PHP code.
• The resulting HTML code, after the highlighting is performed, is not XHTML-compliant. This issue is corrected in PHP5, but in PHP4, the highlighter uses the <font> tag, something that is considered almost a crime by today's Web coders.

Using PEAR: Say Hello to the Text_Highlighter Package

In its repository of PHP libraries, PEAR [7] has a special package for highlighting source code. It's called Text_Highlighter, and its details, documentation and downloads are available [8] online.

This package features:

• The ability to highlight the source code for 12 different programming languages
• Extensiblility; the package allows you to define more languages using a simple XML file
• Line numbering and tab size options are available
• The ability to highlight code in the console window
• Output is provided in XHTML format, using <span> tags for semantics and CSS styles for formatting

A Few Words on the Setup

To prepare your system to run the following examples:

1. Install the PEAR core libraries


2. Install the Text_Highlighter package

Set up your environment, a.k.a. copy my 10-line init.inc.php file

These steps were described in detail in the previous article [9] and are not hard to do. Don't be scared of the word "install" here: it's basically just a "copy" operation. The setup doesn't require you to have any special privileges on the server, and is easily done in low-cost shared hosting environments. If you want to see the directory structure of an example setup, browse the code examples [10] from this article.

Usage

Once you've finished the setup, you can start using the highlighter. In order to highlight the PHP source code contained in, let's say, $some_source_code variable, all you need to do is:

1. Include the class definition:
   require_once 'Text/Highlighter.php';
2. Create an object of the class:
   $highlighter =& Text_Highlighter::factory('php');
3. Call the highlighting method and print the output:
   echo $highlighter->highlight($some_source_code);

Test the Highlighter

Here's a simple script that you can use to test the highlighter package:

<?php
include_once 'init.inc.php';

if (!empty($_POST['text'])){
   
   echo '<link rel="stylesheet" href="hilight.css" />';
   echo '<div style="border: solid 1px orange; padding: 20px; margin: 20px">';
   
   require_once 'Text/Highlighter.php';
   $highlighter =& Text_Highlighter::factory('php');
   echo $highlighter->highlight($_POST['text']);
   
   echo '</div>';
}
?>

<form action="<?php echo $_SERVER['PHP_SELF']?>" method="post">
   <textarea name="text" style="width: 300px; height: 200px"><?php echo @$_POST['text']; ?></textarea>
   <br />
   <input type="submit" />
</form>

Here's a screenshot of the script in action.

You can play around with a live demo here [11].

Colors of the Rainbow

As you can see, the PEAR highlighter is working a lot like the built-in PHP highlighter we looked at first. The only visible difference from the previous example is in the number of colors: there are seven here, rather than the three we saw in the first example. This is made possible because the PEAR highlighter is more granular when it comes to the "ingredients" of the source code.

If you view the source of the result of the script above, you'll see that the highlighting places <span class="hl-something"> tags around the different source code elements. The CSS class names, such as hl-xxxx, need to be defined in order for the coloring to be displayed.

You can take a peek at the CSS file used in the example above [12] if you wish. As you can see, 18 style definitions are used in the CSS file, 15 of which are related to the different elements you might find in a source code file: variables, strings, brackets, quotes, etc. The CSS definitions give you the power to customize the colors used for highlighting as you find appropriate.

It's Not All PHP!

So far, all the examples have focused on coloring PHP code. But what if your site isn't about PHP? Tough luck, some might think, but not the Text_Highlighter package, which offers a colorful hand to 11 other programming and markup languages, including C++, CSS, JavaScript, XML (also used for HTML files), to name a few.

To highlight the code of another language, just change the 'php' in the below line to reflect the language of your choice:

$highlighter =& Text_Highlighter::factory('php');

Want to highlight CSS?

$highlighter =& Text_Highlighter::factory('css');

You can now highlight a CSS stylesheet.

Here's a full list of the language identifiers you can use when creating the highlighter object:

• 'cpp'
• 'css'
• 'diff'
• 'dtd'
• 'javascript'
• 'mysql'
• 'perl'
• 'php'
• 'python'
• 'ruby'
• 'sql'
• 'xml'

You can use this live demo [13] to see how other languages are colored. The source file is available in this article's code archive [14].

As a side note: you've probably noticed already that an object of the highlighter class is created using its factory() method. This is a popular object-oriented technique (an OO pattern). Although an understanding the inner workings of the factory pattern is not required for this article, you can still find out more if you're interested; this PHPPatterns entry [15] is a good starting point.

Fine Tuning the Highlighter

In addition to coloring, the highlighter can:

• Display line numbers along with the source code
• Use different tab sizes to indent code

The first feature can be activated in two ways: using a numbered list (<ol>) or an HTML table. In the latter case, you can use CSS to define a style for the column that contains the numbers, which is different than the one containing the source code.

These options are passed as an array with keys:

• 'numbers': This setting accepts the following values:
  • 0: the default value, meaning no numbering is used
  • HL_NUMBERS_LI: an ordered listing will be used
  • HL_NUMBERS_TABLE: the code will be displayed in a table


• 'tabsize': This option takes an integer value. It sets how many   will be used to replace a tab.

If you choose the table option, you can use the following CSS selectors to customize the look of the table:

• h1-main - for the row with the source code
• hl-gutter - the numbering row
• hl-table - the whole table

Take a look at this article's stylesheet [16] for an example. The three CSS selectors mentioned above can be found at the bottom of the stylesheet.

A sample options array will look like this:

   $options = array(
           'numbers' => HL_NUMBERS_TABLE,
           'tabsize' => 4,
       );

Setting the Options

There are two ways to set the options for highlighting:

1. The easy way: just add the options to the factory method. This is the simpler method in terms of syntax, but it exists only for backwards-compatibility purposes.
   $highlighter =& Text_Highlighter::factory('php', $options);


2. The proper way: use the renderer object.

As mentioned above, in addition to the browser, the highlighter can also color code in the console window. In the future new display devices, like PDAs, phones, your beloved iPod or (last, but not least) your kitchen sink may also be supported -- who knows? To allow for this type of forward-compatibility, the display part of the work is passed to renderer objects. So far, two renderers exist: HTML and Console. All you need to do is create a renderer object, then pass it to the highlighter. Here's how:

   require_once 'Text/Highlighter.php';
   require_once 'Text/Highlighter/Renderer/Html.php';

   $options = array(
           'numbers' => HL_NUMBERS_TABLE,
           'tabsize' => 4,
       );
   
   $renderer =& new Text_Highlighter_Renderer_HTML($options);
   $highlighter =& Text_Highlighter::factory('php');
   $highlighter->setRenderer($renderer);
   echo $highlighter->highlight($_POST['text']);

The full source code listing is available in this article's code archive [17]. A live demo using the HTML renderer and tables to display the source code [18] is also available. Here's a screenshot of the script in action.

Other Options

Here are some other options you might want to take a look at that are not covered in this article.

• GeSHi: Generic Syntax Highlighter [19] - a non-PEAR highlighter package, currently supporting 35 programming languages.
• Aidan Lister's PHP repository contains two classes that use and extend the native PHP coloring. The first class [20] adds line numbers and makes the PHP functions into links to the PHP manual. The second [21] does the same, but in its own way, without the use of the native PHP functions. It also produces XHTML output and can optionally use a stylesheet for color definitions.
• Enscript [22] is a command line tool for syntax highlighting. An example use of it is this WordPress plugin [23].

Summary

In this article, we discussed in detail two ways to highlight source code in your PHP application. If you want to quickly colorize come PHP code, make a call or two to the native highlighting functions that are built into the language. Or, if you want to highlight more languages and have more display options, consider installing a copy of the PEAR's Text_Highlighter package.

You now have a basic knowledge of how to use color coding to enhance the readability of Web pages that contain source code, and improve your visitors' experience.

[1] http://www.sitepoint.com/article/bb-code-php-application
[2] http://php.net/highlight_file
[3] http://php.net/highlight_string
[4] http://www.sitepoint.com/examples/highlightcode/code_archive.zip
[5] http://www.w3clubs.com/sp/hilite/hi_test1.php
[6] http://www.sitepoint.com/article/bb-code-php-application
[7] http://pear.php.net/
[8] http://pear.php.net/package/Text_Highlighter
[9] http://www.sitepoint.com/article/bb-code-php-application
[10] http://www.w3clubs.com/sp/hilite/
[11] http://www.w3clubs.com/sp/hilite/hi_test2.php
[12] http://www.w3clubs.com/sp/hilite/hilight.css
[13] http://www.w3clubs.com/sp/hilite/hi_test3.php
[14] http://www.sitepoint.com/examples/highlightcode/code_archive.zip
[15] http://phppatterns.com/index.php/article/articleview/49/1/1/
[16] http://www.w3clubs.com/sp/hilite/hilight.css
[17] http://www.sitepoint.com/examples/highlightcode/code_archive.zip
[18] http://www.w3clubs.com/sp/hilite/hi_test4.php
[19] http://qbnz.com/highlighter/
[20] http://aidan.dotgeek.org/lib/?file=function.highlight_file_linenum.php
[21] http://aidan.dotgeek.org/lib/?file=PHP_Highlight.php
[22] http://people.ssh.fi/mtr/genscript/
[23] http://scott.yang.id.au/2004/05/syntax-hilight-enscript/