news/2008/3.1.0rc1-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>3.1.0 Release Candidate - 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">3.1.0 Release Candidate</h1>
  19
  20 <div id="content">
  21
  22 <p>
  23     It's never happened before; HTML Purifier is now having its first ever
  24     release candidate! Not since the beta-days has such a momentous event
  25     occurred!
  26 </p>
  27
  28 <p>
  29     All joking aside, there have been some serious changes in the way HTML
  30     Purifier is loaded on the developer-side; needless to say, I will not
  31     be surprised if you see a fat <strong>Fatal</strong> error when you drop
  32     in this release candidate. Some of them are intentional, some of them are
  33     not (well, I hope not!) I need your help to iron out bugs stemming from
  34     different system configurations before I do the official release.
  35 </p>
  36
  37 <blockquote class="digression">
  38     <p>
  39         If you are a <em>new</em> user, you can treat this version as stable and
  40         use it normally. The main uncertainty is with regards to upgrade
  41         paths.
  42     </p>
  43 </blockquote>
  44
  45 <p>
  46     So, if you are willing and ready, grab a copy, and then read on...
  47 </p>
  48
  49 <xi:include href="download-box.xml" xpointer="xpointer(/*/node())" />
  50
  51 <h2>Autoloading</h2>
  52
  53 <p>
  54     Autoloading is singularly the largest architectural change in HTML
  55     Purifier, and under certain circumstances, can give you a hefty performance
  56     boost too (not using the autoloader, but hold onto that thought for a moment).
  57     Previously, HTML Purifier loaded everything it needed from <em>HTMLPurifier.php</em>.
  58     Things have changed a little. I've investigated this thoroughly, and the
  59     following cases will require some
  60     user intervention:
  61 </p>
  62
  63 <h3>You're a <acronym>PEAR</acronym> user</h3>
  64
  65 <p>
  66     Previously, I told you to use this code:
  67 </p>
  68
  69 <pre>require_once 'HTMLPurifier.php';</pre>
  70
  71 <p>
  72     This will no longer be sufficient, because it doesn't register HTML Purifier's
  73     autoloader. Replace the line with:
  74 </p>
  75
  76 <pre>require_once 'HTMLPurifier.auto.php';</pre>
  77
  78 <h3>You included HTMLPurifier.php directly</h3>
  79
  80 <p>
  81     Follow the same instructions as a <acronym>PEAR</acronym> user.
  82 </p>
  83
  84 <h3>You are already using autoloading, and are on a version of PHP earlier than 5.1.2</h3>
  85
  86 <p>
  87     In early versions of PHP 5, there was no way to register multiple autoload
  88     handlers (with <code>spl_autoload_register</code>). You will need to
  89     manually modify your autoloader to get HTML Purifier to play nice with it.
  90 </p>
  91
  92 <p>Suppose your autoload function looks like this:</p>
  93
  94 <pre>function __autoload($class) {
  95     require str_replace('_', '/', $class) . '.php';
  96     return true;
  97 }</pre>
  98
  99 <p>A modified version with HTML Purifier would look like this:</p>
 100
 101 <pre>function __autoload($class) {
 102     if (HTMLPurifier_Bootstrap::autoload($class)) return true;
 103     require str_replace('_', '/', $class) . '.php';
 104     return true;
 105 }</pre>
 106
 107 <p>
 108     Make sure you call <code>HTMLPurifier_Bootstrap::autoload()</code> first,
 109     because it will ignore class names that aren't prefixed with HTMLPurifier.
 110 </p>
 111
 112 <h3>You are already using autoloading, and are on PHP 5.1.2+</h3>
 113
 114 <p>
 115     Congratulations; you probably won't need to make any modifications.
 116     However, it's worth taking a look whether or not you are using
 117     <code>__autoload</code> or <code>spl_autoload_register</code>. If it's the
 118     former, you may want to consider adding this line of code to your
 119     application:
 120 </p>
 121
 122 <pre>spl_autoload_register('__autoload');</pre>
 123
 124 <p>
 125     This is a good idea because <code>spl_autoload_register</code> overrides
 126     any <code>__autoload</code> function, so if a misbehaving library (not HTML Purifier,
 127     of course!) registers its
 128     own autoloader function, yours will mysteriously stop working. You are
 129     <em>required</em> to do this if your autoloader is defined <em>after</em>
 130     HTML Purifier's autoloader is called.
 131 </p>
 132
 133 <h3>Some extra notes</h3>
 134
 135 <p>
 136     With those modifications, your HTML Purifier installation should not be
 137     fatally error'ing out. If it is, please <a href="http://htmlpurifier.org/phorum/list.php?3">post
 138     in the Support forums</a> and I'll try to help and figure it out.
 139 </p>
 140
 141 <p>
 142     If you've got things working, and would like to try some of the newest features
 143     out, check out the following files:
 144 </p>
 145
 146 <dl>
 147     <dt><strong>HTMLPurifier.includes.php</strong></dt>
 148     <dd>This is the performance-friendly file I was talking about earlier. If you
 149     use this, you don't need the autoloader at all&mdash;just swap 'auto' with
 150     'includes'. The downside is that if you are using any non-standard classes,
 151     you'll need to include them manually.</dd>
 152
 153     <dt><strong>HTMLPurifier.kses.php</strong></dt>
 154     <dd>On the prompting of Lukasz Pilorz, I wrote a little wrapper for
 155     HTML Purifier using the kses interface. It's pretty neat and works with
 156     kses's configuration parameters, so check it out if you've got some
 157     legacy code you want to migrate.</dd>
 158
 159     <dt><strong>HTMLPurifier.safe-includes.php</strong></dt>
 160     <dd>This is the not-so-performance-friendly counterpart of
 161     HTMLPurifier.includes.php. On the plus side, however, it doesn't need
 162     autoload, and it can be included from anywhere with impunity.</dd>
 163 </dl>
 164
 165 <h2>Filters</h2>
 166
 167 <p>
 168     The interface for registering filters changed slightly. You may have noticed
 169     some <code>E_USER_WARNING</code>s emitting from code that looks like:
 170 </p>
 171
 172 <pre><![CDATA[$purifier = new HTMLPurifier();
 173 require_once 'HTMLPurifier/Filter/YouTube.php';
 174 $purifier->addFilter(new HTMLPurifier_Filter_YouTube());]]></pre>
 175
 176 <p>
 177     We've replaced <code>addFilter()</code> with some new configuration directives.
 178     Combined with autoloading, the above code turns into:
 179 </p>
 180
 181 <pre><![CDATA[$config = HTMLPurifier_Config::createDefault();
 182 $config->set('Filter', 'YouTube', true);
 183 $purifier = new HTMLPurifier($config);]]></pre>
 184
 185 <p>
 186     If you're using a custom filter, you'll need some slightly different code:
 187 </p>
 188
 189 <pre><![CDATA[$config = HTMLPurifier_Config::createDefault();
 190 $config->set('Filter', 'Custom', array(
 191     new YourCustomFilter()
 192 ));
 193 $purifier = new HTMLPurifier($config);]]></pre>
 194
 195 <h2>Everything else...</h2>
 196
 197 <p>
 198     There may be a few miscellaneous warnings left. If your error-reporting
 199     level includes notices, you might see HTML Purifier complaining about
 200     the usage of deprecated aliases. Don't worry: I'm not going to remove
 201     those aliases, but from a performance standpoint it's a good idea to
 202     convert the old directive to the new directive.
 203 </p>
 204
 205 <p>
 206     From there, it gets highly internal. If you've been making custom modules
 207     for yourself, please note that the signature of
 208     <code>HTMLPurifier_HTMLModule->addElement()</code> has changed; there is
 209     no more <code>$safe</code> parameter. <em>However</em>, there was no
 210     <code>$safe</code> parameter to begin with in
 211     <code>HTMLPurifier_HTMLDefinition->addElement()</code>, so users of that
 212     method don't have to worry about this change. For the curious, this change
 213     is indicative of the shift from element-based safety to module-based
 214     safety. Once I implement more elements and attributes for trusted mode,
 215     there will be more documentation for this.
 216 </p>
 217
 218 <p>
 219     Finally, the static methods in <code>HTMLPurifier_ConfigSchema</code>
 220     were deprecated. They probably still work, although they're not being
 221     actively tested now. If you need to add custom configuration to HTML
 222     Purifier, retrieve a copy of the schema using
 223     <code>HTMLPurifier_ConfigSchema::instance()</code> and then operating
 224     on it using the <code>add*()</code> methods. Some of the method
 225     signatures have changed, most notably there's an extra
 226     <code>$allowsNull</code> parameter after <code>$type</code> in
 227     <code>add()</code>. Extensible configuration
 228     is somewhat an unknown, so if you have definitive use-cases you'd like to
 229     share with me and influence the architecture of this, please say so.
 230     Please <em>do not</em> add your own files to the <code>schema/</code>
 231     directory unless you plan on submitting your changes for incorporation
 232     with the core. For information on how this subsystem works, check out
 233     <a href="http://htmlpurifier.org/docs/dev-config-schema.html">the documentation
 234     on Config Schema</a>.
 235 </p>
 236
 237 <h2>New features!</h2>
 238
 239 <p>
 240     Thanks for putting up with all that backwards-compatibility documentation!
 241     Now we get to the fun stuff: new features. The new features are mostly
 242     all configuration directives:
 243 </p>
 244
 245 <ul>
 246     <li><a href="http://htmlpurifier.org/live/configdoc/plain.html#HTML.Proprietary">%HTML.Proprietary</a>
 247     - Enables some proprietary <abbr>HTML</abbr> elements like <code>marquee</code>.</li>
 248     <li><a href="http://htmlpurifier.org/live/configdoc/plain.html#CSS.AllowImportant">%CSS.AllowImportant</a>
 249     - Enables the !important selector in <abbr>CSS</abbr> code, most useful
 250       in conjunction with the ExtractStyleBlocks filter.</li>
 251     <li><a href="http://htmlpurifier.org/live/configdoc/plain.html#CSS.AllowTricky">%CSS.AllowTricky</a>
 252     - Enables some possibly mischevious <abbr>CSS</abbr> properties, namely <code>display</code> and <code>visibility</code></li>
 253     <li><a href="http://htmlpurifier.org/live/configdoc/plain.html#CSS.AllowedProperties">%CSS.AllowedProperties</a>
 254     - Allows you to control which CSS properties you would like to allow</li>
 255     <li><a href="http://htmlpurifier.org/live/configdoc/plain.html#HTML.ForbiddenAttributes">%HTML.ForbiddenAttributes</a>
 256     - Allows you to blacklist certain HTML attributes</li>
 257     <li><a href="http://htmlpurifier.org/live/configdoc/plain.html#HTML.ForbiddenElements">%HTML.ForbiddenElements</a>
 258     - Allows you to blacklist certain HTML elements</li>
 259 </ul>
 260
 261 <p>
 262     As usual, see <a href="http://htmlpurifier.org/svnroot/htmlpurifier/tags/3.1.0rc1/NEWS">the NEWS</a> for a full list of enhancements
 263     and bugfixes.
 264 </p>
 265
 266 </div>
 267
 268 </body>
 269 </html>