news/2008/3.1.0-released.xhtml

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