html2text

Navigation

Skip navigation.

Site search

Site navigation

Introduction

The html2text PHP script renders HTML as text. Originally designed to construct text based email content from HTML pages, but useful for wherever text representations of HTML are required. Especially good when used with makeMIME. This is similar to how text browsers like Lynx render Web pages, but this script is designed for more restrictive environments, where documents cannot respond to forms or hyperlinks, and features such as text underlines, bold fonts and colours are not available.

Version 2 is a complete rewrite using a totally different approach. The output is compatible with version 1, but with significantly improved functionality. Instead of relying on rudimentary pattern matching, it now uses a proper HTML parser to load and interpret the HTML, then a text rendering engine to determine the layout. The main function may still be called in exactly the same way, meaning that in most cases, the new version can simply be dropped directly in as a replacement for the old one.

Though significantly more complex and a much larger code size, it outperforms version 1 in all respects.

Benefits of version 2+

Limitations of version 2+

Table cell alignment, wordrapping, and the namespace prefix limitations also affect version 1.

Using the script

To use this script library, put the following line in your script before the part that needs it:

require('PATH_TO_FILE/html2text.php');

Then choose the type of conversion that you require - note that only the first type of call to html2text can strip PHP, and even then it may fail if there are encoding problems in the source string:

To convert an HTML/PHP string to text
$textVersion = html2text( $HTMLstring );
To convert an XHTML string to text
$textVersion = html2text( $HTMLstring, true );
To convert an HTML file to a text string
$textVersion = html2text( $filepath, false, true );
To convert an XHTML file to a text string
$textVersion = html2text( $filepath, true, true );
To convert a pre-prepared case-insensitive HTML DOMDocument object (some harmless properties beginning with "h2t_" will be added to the object)
$textVersion = html2text( $domdocumentobject )
To convert a pre-prepared case-sensitive XHTML DOMDocument object (some harmless properties beginning with "h2t_" will be added to the object)
$textVersion = html2text( $domdocumentobject, true )

Note that there are limitations in its ability to strip PHP contained in the HTML string. It can fail to remove all PHP in some circumstances (such as strings containing PHP tags, or encoding problems, as discussed below), and this may expose the contents of the PHP code contained in the HTML string. Ensure that there is no sensitive content in any PHP you pass to the html2text function. For best results, only pass HTML.

Note that depending on the validity of the markup you are using (or the existence of the files you ask it to load), DOMDocument may generate various warnings or notifications.

The returned string will only use Windows line breaks (\r\n), as this is required by RFC2822, the email format specification. Though normally unnecessary, if you need to convert these into Unix line breaks (\n) for whatever reason, use a multibyte-safe function to replace one with the other. For example:

$textVersion = preg_replace( "/\r\n/u", "\n", $textVersion );

Encodings

Encoding problems will occur when you try to feed characters or byte sequences into html2text that are not valid in the encoding that PHP is assuming when interpreting the code. The html2text function attempts to detect and recover from simple encoding issues (be warned that it will not strip PHP from the source string if this happens, and that may expose sensitive contents), and will issue a warning if it detects something wrong. However, it cannot detect all issues, and may fail completely in some cases. You will know that you have a more serious encoding problem with your HTML when some characters appear malformed in the html2text output, or cause the output - or part of the output - to disappear completely.

PHP's own support for unicode is quite poor, and it does not always handle utf-8 correctly. Although the html2text script uses unicode-safe methods (without needing the mbstring module), it cannot always cope with PHP's own handling of encodings. PHP does not really understand unicode or encodings like utf-8, and uses the base encoding of the system, which tends to be one of the ISO-8859 family. As a result, what may look to you like a valid character in your text editor, in either utf-8 or single-byte, may well be misinterpreted by PHP. So even though you think you are feeding a valid character into html2text, you may well not be.

Now add the complications of libxml, used by PHP as the DOMDocument HTML parser. Libxml does recover from some encoding problems, and can sometimes be made to work in other cases by the markup having the correct encoding set in a meta tag before the rest of the content, but it will not always work correctly. For the most reliable response, use HTML entities for all special characters. An alternative is to use XHTML mode with valid XHTML containing an XML prolog specifying the encoding, and make html2text load the markup from a file. If neither of these works, please refer to the PHP documentation for DOMDocument and libxml to find solutions to the problem.

Using one of these approaches, the script can output any unicode character that the target viewer can display, served as utf-8. This is a significant improvement over version 1, which typically just displayed broken characters.

Adding and configuring elements

The script holds formatting information about elements in an array. Once the script has been included, other elements can be added into the array as needed. Existing elements can also have their formatting details redefined as needed. Subsequent calls to html2text will use the updated element details. Note, however, that in HTML mode, libxml may use error handling when it sees unrecognised tags, and it may not build the expected DOM. Custom (non-standard or non-supported) tags are best used only in XHTML mode.

To add or change an element's formatting details, use the following format:

$html2text_elements['tagName'] = Array( isFlow, isPreformatted, isVoid, marginTop, marginBottom, dropFirstChildMargin, before, after, isBeforeFunction, isAfterFunction, dropOnFirst );

The array values are as follows:

isFlow
Boolean: says if the element should be treated as block/flow level (drop any pending spaces, ignore leading whitespace if not preformatted).
isPreformatted
Boolean: says if the element and all its children should be treated as preformatted text (whitespace is not collapsed), like PRE in HTML.
isVoid
Boolean: drops all childNodes completely - for elements whose contents must not be displayed (even if error handling creates contents).
marginTop
Positive integer: minimum number of line breaks to display before this element (basic margin collapsing will take place).
marginBottom
Positive integer: minimum number of line breaks to display after this element (basic margin collapsing will take place).
dropFirstChildMargin
Boolean: ignore marginTop of first rendered childNode (for use where the child must line up with the 'before' content of this element). Recommended only for elements that have some 'before' content. Use in other cases can cause the element's own margin to disappear completely.
before
String: text to insert before element (whitespace is not collapsed).
after
String: text to insert after element (whitespace is not collapsed).
isBeforeFunction
Boolean: execute 'before' as a function instead of treating directly as a text node.
isAfterFunction
Boolean: execute 'after' as a function instead of treating directly as a text node.
dropOnFirst
Boolean: says if the element's 'before' should be ignored if the element is the firstElementChild of its parent. (Note that although this could also be achieved with a 'before' function that checks if the element is a first child, the results are slightly different; if a function returns an empty string, it will not output pending spaces or linebreaks, but it will if dropOnFirst is used instead - this makes it most useful for elements such as a potentially empty table cell.)

The element's tagName should be lower case for HTML, and is case sensitive for XHTML mode. Functions used for 'before' or 'after' will be passed the element node and its childElement index as parameters. They must return a string (return empty strings if no text is wanted).

The following simple example shows how to define the poem element as a preformatted block element for use in X(HT)ML. It will have a large gap above and below, and leading '[' and trailing ']' characters:

$html2text_elements['poem'] = Array(true,true,false,3,3,false,'[',']',false,false,false);

By default, the first and last margins created in the document are ignored. You can change this by redefining the 'the document' virtual element as follows:

//Array( ignore start margin, ignore end margin )
$html2text_elements['the document'] = Array(false,false);

Useful functions

When using functions for 'before' or 'after', there are two utility functions provided by the script, which can help tidy up the values retrieved from element attributes. The first is html2text_cleanspace, which accepts a single string value. It returns a whitespace-collapsed version of the string. The second is html2text_resolve, which accepts two parameters; the first is a string that is a relative or absolute URL, and the second is the element that was passed to the initial function. It returns a resolved URL if a BASE HREF tag has been found, or if not, it just returns the string it was passed. If no BASE HREF has been found yet, and the string passed to the function contains only a HTML fragment identifier, it returns an empty string.

The following example assumes the poem element has both an author attribute containing the author's name, and a url attribute, pointing to the author's website. It shows how to extract and clean/resolve those attributes, using a 'before' function, and the utility functions:

$html2text_elements['poem'] = Array(true,true,false,3,3,false,'poemdetail',']',true,false,false);
function poemdetail($element,$index) {
  $author = $url = '';
  if( $element->hasAttribute('author') ) {
    $author = html2text_cleanspace($element->getAttribute('author'));
  }
  if( $element->hasAttribute('url') ) {
    $url = html2text_resolve($element->getAttribute('url'),$element);
  }
  return '['.$author.($url?(' '.$url):'').(($author||$url)?"\r\n":'');
}

To download the script(s), and see the script license, use the links on the navigation panel at the top of this page.

This site was created by Mark "Tarquin" Wilton-Jones.
Don't click this link unless you want to be banned from our site.