Complete migration to new News format.
[htmlpurifier-web.git] / news / 2008 / 3.1.0-released.xhtml
blob39a608d30fb2680a4ee484bd6800310058120f9d
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4 <html
5 xmlns="http://www.w3.org/1999/xhtml"
6 xmlns:xi="http://www.w3.org/2001/XInclude"
7 xmlns:xc="urn:xhtml-compiler"
8 xml:lang="en">
9 <head>
10 <title>HTML Purifier 3.1.0 released - News - HTML Purifier</title>
11 <xi:include href="common-meta.xml" xpointer="xpointer(/*/node())" />
12 <meta name="description" content="Release candidate notice for HTML Purifier 3.1.0rc1." />
13 <meta name="keywords" content="HTMLPurifier, HTML Purifier, HTML, filter, filtering, standards, compliant, 3.1.0, 3.1.0rc1, candidate, release, version, news" />
14 </head>
15 <body>
17 <xi:include href="common-header.xml" xpointer="xpointer(/*/node())" />
18 <h1 id="title">HTML Purifier 3.1.0 released</h1>
20 <div id="content">
22 <p>
23 HTML Purifier 3.1 represents a major shift from a <abbr>PHP</abbr> 4
24 centric codebase to a <abbr>PHP</abbr> 5, whereas HTML Purifier 3.0
25 was merely done for <code>E_STRICT</code> compliance. As such, it
26 poses some migration concerns that should be addressed, most
27 prominently HTML Purifier's new usage of the autoload system.
28 </p>
30 <xi:include href="download-box.xml" xpointer="xpointer(/*/node())" />
32 <h2>Autoloading</h2>
34 <p>
35 Autoloading is singularly the largest architectural change in HTML
36 Purifier, and under certain circumstances, can give you a hefty performance
37 boost too (not using the autoloader, but hold onto that thought for a moment).
38 Previously, HTML Purifier loaded everything it needed from <em>HTMLPurifier.php</em>.
39 Things have changed a little. I've investigated this thoroughly, and the
40 following cases will require some
41 user intervention:
42 </p>
44 <h3>You're a <acronym>PEAR</acronym> user</h3>
46 <p>
47 Previously, I told you to use this code:
48 </p>
50 <pre>require_once 'HTMLPurifier.php';</pre>
52 <p>
53 This will no longer be sufficient, because it doesn't register HTML Purifier's
54 autoloader. Replace the line with:
55 </p>
57 <pre>require_once 'HTMLPurifier.auto.php';</pre>
59 <h3>You included HTMLPurifier.php directly</h3>
61 <p>
62 Follow the same instructions as a <acronym>PEAR</acronym> user.
63 </p>
65 <h3>You are already using autoloading, and are on a version of PHP earlier than 5.1.2</h3>
67 <p>
68 In early versions of PHP 5, there was no way to register multiple autoload
69 handlers (with <code>spl_autoload_register</code>). You will need to
70 manually modify your autoloader to get HTML Purifier to play nice with it.
71 </p>
73 <p>Suppose your autoload function looks like this:</p>
75 <pre>function __autoload($class) {
76 require str_replace('_', '/', $class) . '.php';
77 return true;
78 }</pre>
80 <p>A modified version with HTML Purifier would look like this:</p>
82 <pre>function __autoload($class) {
83 if (HTMLPurifier_Bootstrap::autoload($class)) return true;
84 require str_replace('_', '/', $class) . '.php';
85 return true;
86 }</pre>
88 <p>
89 Make sure you call <code>HTMLPurifier_Bootstrap::autoload()</code> first,
90 because it will ignore class names that aren't prefixed with HTMLPurifier.
91 </p>
93 <h3>You are already using autoloading, and are on PHP 5.1.2+</h3>
95 <p>
96 Congratulations; you probably won't need to make any modifications.
97 However, it's worth taking a look whether or not you are using
98 <code>__autoload</code> or <code>spl_autoload_register</code>. If it's the
99 former, you may want to consider adding this line of code to your
100 application:
101 </p>
103 <pre>spl_autoload_register('__autoload');</pre>
106 This is a good idea because <code>spl_autoload_register</code> overrides
107 any <code>__autoload</code> function, so if a misbehaving library (not HTML Purifier,
108 of course!) registers its
109 own autoloader function, yours will mysteriously stop working. You are
110 <em>required</em> to do this if your autoloader is defined <em>after</em>
111 HTML Purifier's autoloader is called.
112 </p>
114 <h3>Some extra notes</h3>
117 With those modifications, your HTML Purifier installation should not be
118 fatally error'ing out. If it is, please <a href="http://htmlpurifier.org/phorum/list.php?3">post
119 in the Support forums</a> and I'll try to help and figure it out.
120 </p>
123 If you've got things working, and would like to try some of the newest features
124 out, check out the following files:
125 </p>
127 <dl>
128 <dt><strong>HTMLPurifier.includes.php</strong></dt>
129 <dd>This is the performance-friendly file I was talking about earlier. If you
130 use this, you don't need the autoloader at all&mdash;just swap 'auto' with
131 'includes'. The downside is that if you are using any non-standard classes,
132 you'll need to include them manually.</dd>
134 <dt><strong>HTMLPurifier.kses.php</strong></dt>
135 <dd>On the prompting of Lukasz Pilorz, I wrote a little wrapper for
136 HTML Purifier using the kses interface. It's pretty neat and works with
137 kses's configuration parameters, so check it out if you've got some
138 legacy code you want to migrate.</dd>
140 <dt><strong>HTMLPurifier.safe-includes.php</strong></dt>
141 <dd>This is the not-so-performance-friendly counterpart of
142 HTMLPurifier.includes.php. On the plus side, however, it doesn't need
143 autoload, and it can be included from anywhere with impunity.</dd>
144 </dl>
146 <h2>Filters</h2>
149 The interface for registering filters changed slightly. You may have noticed
150 some <code>E_USER_WARNING</code>s emitting from code that looks like:
151 </p>
153 <pre><![CDATA[$purifier = new HTMLPurifier();
154 require_once 'HTMLPurifier/Filter/YouTube.php';
155 $purifier->addFilter(new HTMLPurifier_Filter_YouTube());]]></pre>
158 We've replaced <code>addFilter()</code> with some new configuration directives.
159 Combined with autoloading, the above code turns into:
160 </p>
162 <pre><![CDATA[$config = HTMLPurifier_Config::createDefault();
163 $config->set('Filter', 'YouTube', true);
164 $purifier = new HTMLPurifier($config);]]></pre>
167 If you're using a custom filter, you'll need some slightly different code:
168 </p>
170 <pre><![CDATA[$config = HTMLPurifier_Config::createDefault();
171 $config->set('Filter', 'Custom', array(
172 new YourCustomFilter()
174 $purifier = new HTMLPurifier($config);]]></pre>
176 <h2>Everything else...</h2>
178 <h3>Configuration aliases</h3>
181 There may be a few miscellaneous warnings left. If your error-reporting
182 level includes notices, you might see HTML Purifier complaining about
183 the usage of deprecated aliases. Don't worry: I'm not going to remove
184 those aliases, but from a performance standpoint it's a good idea to
185 convert the old directive to the new directive.
186 </p>
188 <h3>tag.attr to tag@attr</h3>
191 If you were using %HTML.AllowedAttributes, it is recommended that you upgrade your syntax
192 from tag.attr to tag@attr. While the two are functionally equivalent,
193 and the dot-syntax will not be deprecated any time soon, this modification
194 is made with an eye towards future compatibility with XML: XML permits
195 tag names to have periods. %HTML.ForbiddenAttributes will <em>only</em>
196 allow the at-sign-syntax, and will output an informative error message
197 if you do otherwise.
198 </p>
200 <h3>HTMLPurifier_HTMLModule->addElement()</h3>
203 From there, it gets highly internal. If you've been making custom modules
204 for yourself, please note that the signature of
205 <code>HTMLPurifier_HTMLModule->addElement()</code> has changed; there is
206 no more <code>$safe</code> parameter. <em>However</em>, there was no
207 <code>$safe</code> parameter to begin with in
208 <code>HTMLPurifier_HTMLDefinition->addElement()</code>, so users of that
209 method don't have to worry about this change. For the curious, this change
210 is indicative of the shift from element-based safety to module-based
211 safety. Once I implement more elements and attributes for trusted mode,
212 there will be more documentation for this.
213 </p>
215 <h3>HTMLPurifier_ConfigSchema::<em>method</em></h3>
218 The static methods in <code>HTMLPurifier_ConfigSchema</code>
219 were deprecated. They probably still work, although they're not being
220 actively tested now. If you need to add custom configuration to HTML
221 Purifier, retrieve a copy of the schema using
222 <code>HTMLPurifier_ConfigSchema::instance()</code> and then operating
223 on it using the <code>add*()</code> methods. Some of the method
224 signatures have changed, most notably there's an extra
225 <code>$allowsNull</code> parameter after <code>$type</code> in
226 <code>add()</code>. Extensible configuration
227 is somewhat an unknown, so if you have definitive use-cases you'd like to
228 share with me and influence the architecture of this, please say so.
229 Please <em>do not</em> add your own files to the <code>schema/</code>
230 directory unless you plan on submitting your changes for incorporation
231 with the core. For information on how this subsystem works, check out
232 <a href="http://htmlpurifier.org/docs/dev-config-schema.html">the documentation
233 on Config Schema</a>.
234 </p>
236 <h3>Return by reference</h3>
239 A number of methods that returned explict references to objects
240 now merely return objects. Due to PHP 5's new object system, objects are
241 passed automatically by reference, making an ampersand unnecessary.
242 If you have code that does this:
243 </p>
245 <pre><![CDATA[$def =& $config->getHTMLDefinition();]]></pre>
248 ...it will throw an <code>E_STRICT</code> error. The fix is:
249 </p>
251 <pre><![CDATA[$def = $config->getHTMLDefinition();]]></pre>
253 <h3>HTMLPurifier_Printer_ConfigForm::get*()</h3>
256 HTMLPurifier_Printer_ConfigForm::getCSS() and
257 HTMLPurifier_Printer_ConfigForm::getJavascript() should be called statically,
258 not from an instance variable. Change:
259 </p>
261 <pre><![CDATA[$css = $form->getCSS();]]></pre>
264 ...to:
265 </p>
267 <pre><![CDATA[$css = HTMLPurifier_Printer_ConfigForm::getCSS();]]></pre>
269 <h2>New features!</h2>
272 Thanks for putting up with all that backwards-compatibility documentation!
273 Now we get to the fun stuff: new features. The new features are mostly
274 all configuration directives:
275 </p>
277 <ul>
278 <li><a href="http://htmlpurifier.org/live/configdoc/plain.html#HTML.Proprietary">%HTML.Proprietary</a>
279 - Enables some proprietary <abbr>HTML</abbr> elements like <code>marquee</code>.</li>
280 <li><a href="http://htmlpurifier.org/live/configdoc/plain.html#CSS.AllowImportant">%CSS.AllowImportant</a>
281 - Enables the !important selector in <abbr>CSS</abbr> code, most useful
282 in conjunction with the ExtractStyleBlocks filter.</li>
283 <li><a href="http://htmlpurifier.org/live/configdoc/plain.html#CSS.AllowTricky">%CSS.AllowTricky</a>
284 - Enables some possibly mischevious <abbr>CSS</abbr> properties, namely <code>display</code> and <code>visibility</code></li>
285 <li><a href="http://htmlpurifier.org/live/configdoc/plain.html#CSS.AllowedProperties">%CSS.AllowedProperties</a>
286 - Allows you to control which CSS properties you would like to allow</li>
287 <li><a href="http://htmlpurifier.org/live/configdoc/plain.html#HTML.ForbiddenAttributes">%HTML.ForbiddenAttributes</a>
288 - Allows you to blacklist certain HTML attributes</li>
289 <li><a href="http://htmlpurifier.org/live/configdoc/plain.html#HTML.ForbiddenElements">%HTML.ForbiddenElements</a>
290 - Allows you to blacklist certain HTML elements</li>
291 </ul>
294 HTML Purifier 3.1.0 also boasts a far more robust URI handling system.
295 URIs such as http://zh.wikipedia.org/wiki/首頁 are converted into
296 http://zh.wikipedia.org/wiki/%E9%A6%96%E9%A1%B5 (previously, they
297 were incorrectly left in IRI form.)
298 </p>
301 As usual, see <a href="http://htmlpurifier.org/svnroot/htmlpurifier/tags/3.1.0/NEWS">the NEWS</a> for a full list of enhancements
302 and bugfixes.
303 </p>
305 </div>
307 </body>
308 </html>