Htmlys manual for PHP
Load the extension into PHP
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.
If you can modify your
php.ini, the easiest way is to add the line:
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.
.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
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
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.
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_file(). They are defined like so:
- 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_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.
Here is an example script using the extension, feel free to adapt it to your needs:
- * 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();
- '<!DOCTYPE html>
- <meta charset="utf-8" />
- <body class="test">
- This a test HTML document
- <!-- a comment here -->
- // /path/to/document.html has to exist
- html_parse_file($handler, '/path/to/document.html');