Documentation - PHP bugs

PHP bugs

DOM extension for php has a lot of problems. Those problems bleed-through to DOMtempl.

Auto-conversion

DOMtempl WILL NOT pre-process your template to fix the after-mentioned bugs.

This is done to allow libxml2 errors and warnings to be generated relatively to the original files with original line numbers.

Therefore, you must take some care of your templates. Despite this page looking scary, the benefit of using DOMtempl still out-weights other solutions.

HTML vs XML

Because php DOM extension is based on libxml2, only HTML4.0 parsing3 is supported.

Thus, HTML5 could not be correctly loaded. XML, on the other hand, is fine.

Thus, DOMtempl always treats your HTML as XML. This brings in some unfortunate consequences:

Your templates must be valid XML. Thankfully, HTML5 is allowed to be written as XML, i.e. XHTML5.

The most notable difference is the treatment of void elements, they should always be written as XML shorttags.

I.e. <link> should be written as <link/>, meta as <meta/>, and, most annoyingly, <img> as <img/>.

Thankfully, this is supported by HTML5 spec.

Encoding

As explained here1, the libxml2 library peeks at the <META> tags to figure out the encoding used.

That doesn't sound too bad, simply include a meta-encoding tag at the top of your document.

However, the new'ish HTML5 short meta-encoding

<meta encoding="UTF-8">

will NOT work, as only HTML4.0 is supported by libxml2. Thus, an older, longer version must be used:

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

Thankfully, this is still valid in HTML5.

Entities

XML only allows the following entities:

&amp;, &lt;, &gt;, &quot; and &apos;

Thus, HTML entities2 are not allowed.

This might break your template.

The workaround is to use the actual Unicode character, instead of the entity. Thankfully, this is valid in HTML5.

Those generally work great, but could be inconvenient in some cases.

For example, the most popular HTML entity --   -- looks like a regular whitespace when printed, as is not very readable.

You can extend your DOCTYPE declaration to include it, like this:

<!DOCTYPE html [
<!ENTITY nbsp "&#160;">
<!ENTITY mdash "—">
]>

Yes, this sucks.

Furthermore, such extended DOCTYPE will not be kept when the template is rendered, and will be replaced with a simple <!DOCTYPE html>. This might provide further inconvenience.

TL;DR

You have to take extra care of your HTML5 templates. Luckily, all required changes do conform to the HTML5 spec.

Use self-closing XML shorttags for meta, link, img and other void elements.
Use actual unicode characters instead of entities.
Use HTML4.0-style meta charset declaration. Make sure it's on the top of the document.