Webstuff.Inblighty.Com

Fed up with HTML encoding your source code etc? This lazy blogger article for Apache sites identifies quick ways to create source code listings (including syntax colored PHP) for your tutorials and posts; both as standalone pages and within article content.

006# EXAMPLE SNIPPET
007$score = 1 + 2;
008$msg .= 'Score = ' . $score . ' points'
009echo $msg;

I’ve also included work-rounds for WordPress and other CMS sites that do not allow execution of php within posts.

As with every article on this site: it may work for me but I make no guarantee that what I publish will be safe for your site. Use at your own risk.

1. Use ‘.phps’ files to display source code

On many servers, including this one; files with a ‘.phps’ extension are automatically HTML encoded on output to display as coloured source code.

So all you need is a copy of your code in a ‘phps’ file on your server; and a link to it in your article or tutorial. Example: /publicsource/highlightwithstyles.phps

• great for providing your readers with an easy to cut and paste complete source listing
• you can “view source” of the “phps file” in your browser and paste the complete html encoded listing into your posts

• displayed on a separate page
• difficult to copy snippets for use in your tutorials due to quantity of generated inline styles and lack of line breaks in the encoded source

My server isn’t configured for ‘phps’ !!!

If you have access to httpd.conf try adding: “AddType application/x-httpd-php-source .phps“.

Alternatively try adding the following to htaccess:

<FilesMatch "\.phps$">
  SetHandler application/x-httpd-php-source
</FilesMatch>

2. highlight_file/highlight_string

PHP’s highlight_file function uses the same syntax highlighter as phps files to echo the code of the specified file. Just insert a “<?php highlight_file('path/your_file.ext') ?>” statement in your tutorial at the point you want your code listing to appear.

The highlight_string function works in exactly the same way except it takes a string as input (useful for snippets).

• quick and simple
• displayed in your article at the appropriate place.

• may not work in posts on WordPress and similar systems (see para immediately below)
• default colors may not match your tutorial and website styles (solution below)
• uses inline styles not CSS classes (but you CAN get highlight_file to use classes)
• no line numbers (solution below)

Standard WordPress does not allow the execution of PHP within posts, however plugins to enable execution are available from WordPress.Org. I guess other systems may have similar restrictions and mods. I would caution against using such plugins as you are adding another potential point of failure in your security.

Instead, use highlight_file as a standalone page outside of WordPress. e.g. <?php highlight_file($_SERVER['DOCUMENT_ROOT'].'/your_code.php'); ?> If you can’t get phps to work on your server you can use higlight_file as an alternative. Specifying “yourcode.php” in the above example would produce the same browser output as yourcode.phps.

You can use highlight_file to generate encoded HTML that you can cut and paste complete with custom colors and styles and/or line numbers.

2a. using custom colors with highlight_file or highlight_string

The syntax highlighter default colors are defined in php.ini by (highlight.comment, highlight.default, highlight.html, highlight.keyword and highlight.string).
As these “variables” simply define what goes between style=" and " we can both change colors and add additional styling by using ini_set as in this example:

<?php
# Using highlight_file with custom styles
# this script lists itself
ini_set('highlight.comment', 'brown; font-weight: bold; font-style:italic');
ini_set('highlight.string', 'red; background-color:yellow');
ini_set('highlight.html', '#000000');
/* we will use the defaults for 
 highlight.keyword & highlight.default */ 
highlight_file('highlightwithstyles.php');
?>

Because I am using WordPress I couldn’t embed the above in my post, so I had to run the PHP as a separate file and paste the output into this post.

Obviously you can change the styles and make the filename to be listed an input variable, but make sure you thoroughly sanitise the input and restrict which files can be source listed. I prefer to edit the hard coded filename as and when I need a listing.

3. Use a script to add line numbers

Various examples of adding line numbers to highlight_file output are provided in the comments for this function at php.net. However, because I am using WordPress I wanted a script that would allow me to easily identify and cut and paste selected lines into my posts.

My attempt starts each line of source on a new line and starts with a line number comment; so it is easy to identify what to copy and paste:

<!-- line 6 --><span style="border-right: 1px solid grey; color: black; text-align: right; padding: 0 0.2em; margin-right: 0.5em;">006</span>
<span style="color: #ff8000;"># EXAMPLE SNIPPET</span>
<!-- line 7 --><span style="border-right: 1px solid grey; color: black; text-align: right; padding: 0 0.2em; margin-right: 0.5em;">007</span>
<span style="color: #0000bb;">$score </span><span style="color: #007700;">= </span><span style="color: #0000bb;">1 </span><span style="color: #007700;">+ </span><span style="color: #0000bb;">2</span><span style="color: #007700;">;</span>

006# EXAMPLE SNIPPET
007$score = 1 + 2;

The line numbering script:

001<?php
002/* author: Andy Wrigley webstuff.inblighty.com
003adds line numbers to output from highlight_file
004NOT THOROUGHLY TESTED - USE AT YOUR OWN RISK */
005
006# EDIT TO LIST YOUR FILE
007$aw_source = highlight_file('your_sourcefile.ext',TRUE);
008
009$aw_source = str_replace('<code>', '' , $aw_source );
010$aw_source = str_replace("\n", '', $aw_source);
011$aw_source = trim($aw_source);
012$aw_source = str_replace('<br /></span>', '</span><br />' , $aw_source );
013$aw_lines = explode("<br />", $aw_source);
014echo "<code>\n<!-- line 1 -->";
015$i = 1;
016foreach ($aw_lines as $aw_line){
017# EDIT YOUR LINE NUMBERING STYLE
018  echo '<span style="border-right:1px solid grey;color:black;';
019  echo 'text-align:right;padding:0 0.2em;margin-right:0.5em">';
020  echo sprintf("%03d",$i++) .'</span>'; 
021  echo $aw_line . "<br />\n<!-- line " . $i . ' -->';
022}?>

See numbered_source.phps for a commented listing of the above script (not numbered for easy copy paste). Most of the code is explained in this post: highlight_file with line numbers and CSS classes”.

Issues: occasionally you may have to insert a span with inline style before the start of your snippet. This is because PHP’s syntax highlighter only creates a span and style on change of syntax e.g. if you copy your snippet from a comment on line 4 but comments start on line 2 the “missing span” will be on line 2.

But don’t forget this is a lazy blogger post, the script does an excellent job and it is easier for me to occasionally make a few minor edits to the output HTML, rather than spend time perfecting the script (suggestions welcome).

If you modify this script, or write your own, to accept filename and line numbers as input; make sure you sanitise the input and restrict the files that can be source listed.

Using CSS classes with highlight_file and highlight_string

Using CSS classes instead of inline styles will result in more readable and compact HTML. See this simple way to get highlight_file and highlight_string to use CSS classes instead of inline styles.

Editors

There may be editors or editor plugins that will do a similar conversion job. But with my lazy blogger hat on; I haven’t got the time to search, download, install, and learn to use them. Recommendations welcome.

Shameless plug: If you find this article interesting or useful then please give it a “+1” at the top of the page.