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