Htmlys manual for PHP

Load the extension into PHP

There are many ways to load the Htmlys extension into PHP. In this manual, we cover the most common cases.

In most cases, relative paths can be used as long as the extension lies in the extension_dir configured in your php.ini, or in the default extension_dir compiled into PHP, if extension_dir is not set.

From the php.ini

If you can modify your php.ini, the easiest way is to add the line:

E-mail Print

extension=/path/to/html.so

And restart your web server if required for the changes to take effect.

If you cannot modify your php.ini (because you are on a shared host, for example), be aware of the fact that you can sometimes create your own php.ini at the root of your website and put directives of your choice inside (some restrictions may have been set by the administrator), including the one stated above. On some systems though, the name of this configuration file is different, use the phpinfo() function to get it or ask your hosting provider/system administrator for more details.

From an .htaccess (Apache only)

For security reasons, it is not possible to load an extension directly from an .htaccess file at the time of this writing (PHP 5.4.3, Apache 2.4), but because PHP already supports changing most values from these files, it may become possible in a future release of PHP.

When you are using Apache though, .htaccess files can still be used to set a custom location of your CGI binary of PHP, which can in turn load the php.ini of your choice. See loading the extension from the CGI environment for more information.

From the command line

If you are using PHP with the CLI or CGI SAPIIf you are using PHP with the CLI or CGI SAPIs, you can instruct it to load the extension directly on the command line, like this:

php -d extension=/path/to/html.so -f script.php

This is ideal to test your scripts (or the extension itself) because it does not require to change the configuration of PHP and the web server (and its possible restart).

From the CGI environment

If you are using PHP with the CGI SAPI, be aware of the fact that it automatically loads any php.ini located in the same directory as the CGI binary of PHP. If you have sufficient rights on the file system, create a php.ini here, and use the php.ini directive stated earlier for a similar effect.

If you don't have the rights to create a file in this location, you may still copy the CGI binary of PHP in a directory where you have writing privileges (eg. cgi-bin at the root of your website), and create the required php.ini in the same directory, but you would still need to alter the configuration of your web server to use this copy of the CGI binary of PHP instead of the default one. On some Apache configurations, this can be done simply by changing the .htaccess. Please, note that if you use this method and put a PHP binary under your web root, special care has to be taken about the security of your website, as warned by the PHP team.

From PHP code

Another way to load the extension is to do it directly from PHP code, using the dl() function:

E-mail Print

<?php
dl('/path/to/html.so');
// Start using the extension here
?>

One could consider this method as the most portable, since PHP scripts can decide to load or not he library at run time, and provide fallback capabilities if not loaded. The method is however discouraged by PHP, and as such, the dl() function is not available in all SAPIs.

Other configurations

If none of the above methods is suitable for your system, or if you need more information about your specific configuration, please check the PHP website for more information.

Use the extension

Once loaded in, the extension provides to the PHP developer one abstract class HtmlHandler and two functions html_parse_string() and html_parse_file(). They are defined like so:

E-mail Print

<?php
abstract class HtmlHandler
{
	public function OnParseError();
	public function OnDoctype(string $name, string $publicId, string $systemId);
	public function OnStartTag(string $name, array $attributes, bool $selfClosing);
	public function OnEndTag(string $name);
	public function OnComment(string $data);
	public function OnChar(string $c);
	public function OnEof();
}
 
bool function html_parse_string(HtmlHandler $handler, string $string);
bool function html_parse_file(HtmlHandler $handler, string $path);
?>

First, the class HtmlHandler has to be extended into your own class, and it should override the methods of the HTML tokens you are interested in. Then, an object of your class has to be instantiated, and the functions html_parse_string() and/or html_parse_file() called with this object as the first parameter.

The second parameter of html_parse_string() has to be plain HTML code, while the second parameter of html_parse_file() has to be a path to an HTML file on your filesystem. Both functions will parse the HTML content and call the methods of your HtmlHandler object as needed.

Example

Here is an example script using the extension, feel free to adapt it to your needs:

E-mail Print

<?php
/*
 * Htmlys demonstration script.
 * -----------------------------------------------------------------------------
 * Copyright (c) 2009 - 2013 Krizalys (http://www.krizalys.com/)
 *
 * Script to demonstate the use of the Htmlys binding for PHP. All the methods
 * have an empty body and could be implemented freely by the developer. Methods
 * that are not needed can be removed.
 *
 * Call to functions html_parse_string() and html_parse_file() can be adjusted
 * or removed as needed.
 */
 
class MyHtmlHandler extends HtmlHandler
{
	public function OnParseError()
	{
		// Handle parse error
	}
 
	public function OnDoctype($name, $publicId, $systemId)
	{
		// Handle DOCTYPE token
	}
 
	public function OnStartTag($name, $attributes, $selfClosing)
	{
		// Handle start tag token
	}
 
	public function OnEndTag($name)
	{
		// Handle end tag token
	}
 
	public function OnComment($data)
	{
		// Handle comment token
	}
 
	public function OnChar($c)
	{
		// Handle character token
	}
 
	public function OnEof()
	{
		// Handle EOF token
	}
}
 
$handler = new MyHtmlHandler();
 
html_parse_string($handler,
'<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>Test</title>
</head>
<body class="test">
This a test HTML document
<!-- a comment here -->
</body>
</html>
');
 
// /path/to/document.html has to exist
html_parse_file($handler, '/path/to/document.html');
?>