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 <h1 id="title">HTML Purifier 3.1.0 released</h1>
  19
  20 <div id="content">
  21
  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>
  29
  30 <xi:include href="download-box.xml" xpointer="xpointer(/*/node())" />
  31
  32 <h2>Autoloading</h2>
  33
  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>
  43
  44 <h3>You're a <acronym>PEAR</acronym> user</h3>
  45
  46 <p>
  47   Previously, I told you to use this code:
  48 </p>
  49
  50 <pre>require_once 'HTMLPurifier.php';</pre>
  51
  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>
  56
  57 <pre>require_once 'HTMLPurifier.auto.php';</pre>
  58
  59 <h3>You included HTMLPurifier.php directly</h3>
  60
  61 <p>
  62   Follow the same instructions as a <acronym>PEAR</acronym> user.
  63 </p>
  64
  65 <h3>You are already using autoloading, and are on a version of PHP earlier than 5.1.2</h3>
  66
  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>
  72
  73 <p>Suppose your autoload function looks like this:</p>
  74
  75 <pre>function __autoload($class) {
  76   require str_replace('_', '/', $class) . '.php';
  77   return true;
  78 }</pre>
  79
  80 <p>A modified version with HTML Purifier would look like this:</p>
  81
  82 <pre>function __autoload($class) {
  83   if (HTMLPurifier_Bootstrap::autoload($class)) return true;
  84   require str_replace('_', '/', $class) . '.php';
  85   return true;
  86 }</pre>
  87
  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>
  92
  93 <h3>You are already using autoloading, and are on PHP 5.1.2+</h3>
  94
  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>
 102
 103 <pre>spl_autoload_register('__autoload');</pre>
 104
 105 <p>
 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>
 113
 114 <h3>Some extra notes</h3>
 115
 116 <p>
 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>
 121
 122 <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>
 126
 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>
 133
 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>
 139
 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>
 145
 146 <h2>Filters</h2>
 147
 148 <p>
 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>
 152
 153 <pre><![CDATA[$purifier = new HTMLPurifier();
 154 require_once 'HTMLPurifier/Filter/YouTube.php';
 155 $purifier->addFilter(new HTMLPurifier_Filter_YouTube());]]></pre>
 156
 157 <p>
 158   We've replaced <code>addFilter()</code> with some new configuration directives.
 159   Combined with autoloading, the above code turns into:
 160 </p>
 161
 162 <pre><![CDATA[$config = HTMLPurifier_Config::createDefault();
 163 $config->set('Filter', 'YouTube', true);
 164 $purifier = new HTMLPurifier($config);]]></pre>
 165
 166 <p>
 167     If you're using a custom filter, you'll need some slightly different code:
 168 </p>
 169
 170 <pre><![CDATA[$config = HTMLPurifier_Config::createDefault();
 171 $config->set('Filter', 'Custom', array(
 172     new YourCustomFilter()
 173 ));
 174 $purifier = new HTMLPurifier($config);]]></pre>
 175
 176 <h2>Everything else...</h2>
 177
 178 <h3>Configuration aliases</h3>
 179
 180 <p>
 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>
 187
 188 <h3>tag.attr to tag@attr</h3>
 189
 190 <p>
 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>
 199
 200 <h3>HTMLPurifier_HTMLModule->addElement()</h3>
 201
 202 <p>
 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>
 214
 215 <h3>HTMLPurifier_ConfigSchema::<em>method</em></h3>
 216
 217 <p>
 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>
 235
 236 <h3>Return by reference</h3>
 237
 238 <p>
 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>
 244
 245 <pre><![CDATA[$def =& $config->getHTMLDefinition();]]></pre>
 246
 247 <p>
 248   ...it will throw an <code>E_STRICT</code> error. The fix is:
 249 </p>
 250
 251 <pre><![CDATA[$def = $config->getHTMLDefinition();]]></pre>
 252
 253 <h3>HTMLPurifier_Printer_ConfigForm::get*()</h3>
 254
 255 <p>
 256   HTMLPurifier_Printer_ConfigForm::getCSS() and
 257   HTMLPurifier_Printer_ConfigForm::getJavascript() should be called statically,
 258   not from an instance variable. Change:
 259 </p>
 260
 261 <pre><![CDATA[$css = $form->getCSS();]]></pre>
 262
 263 <p>
 264   ...to:
 265 </p>
 266
 267 <pre><![CDATA[$css = HTMLPurifier_Printer_ConfigForm::getCSS();]]></pre>
 268
 269 <h2>New features!</h2>
 270
 271 <p>
 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>
 276
 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>
 292
 293 <p>
 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>
 299
 300 <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>
 304
 305 </div>
 306
 307 </body>
 308 </html>