diff --git a/NEWS b/NEWS index 7cb9ba57..427aa132 100644 --- a/NEWS +++ b/NEWS @@ -9,7 +9,11 @@ NEWS ( CHANGELOG and HISTORY ) HTMLPurifier . Internal change ========================== -4.2.1, unknown release date +4.3.0, unknown release date +# Fixed broken caching of customized raw definitions, but requires an + API change. The old API still works but will emit a warning, + see http://htmlpurifier.org/docs/enduser-customize.html#optimized + for how to upgrade your code. ! Added %HTML.Nofollow to add rel="nofollow" to external links. ! More types of SPL autoloaders allowed on later versions of PHP. ! Implementations for position, top, left, right, bottom, z-index @@ -24,6 +28,8 @@ NEWS ( CHANGELOG and HISTORY ) HTMLPurifier This safety check is only done for HTMLPurifier.auto.php; if you are using standalone or the specialized includes files, you're expected to know what you're doing. +- Stop repeatedly writing the cache file after I'm done customizing a + raw definition. 4.2.0, released 2010-09-15 ! Added %Core.RemoveProcessingInstructions, which lets you remove diff --git a/docs/enduser-customize.html b/docs/enduser-customize.html index 42756f11..7e1ffa26 100644 --- a/docs/enduser-customize.html +++ b/docs/enduser-customize.html @@ -146,7 +146,9 @@
$config = HTMLPurifier_Config::createDefault(); $config->set('HTML.DefinitionID', 'enduser-customize.html tutorial'); $config->set('HTML.DefinitionRev', 1); -$def = $config->getHTMLDefinition(true);+if ($def = $config->maybeGetRawHTMLDefinition()) { + // our code will go here +}
Assuming that HTML Purifier has already been properly loaded (hint: @@ -174,23 +176,15 @@ $def = $config->getHTMLDefinition(true);
HTMLPurifier_HTMLDefinition
- object that we will be tweaking. If the parameter was removed, we
- would be retrieving a fully formed definition object, which is somewhat
- useless for customization purposes.
+ object that we will be tweaking. Interestingly enough, we have
+ placed it in an if block: this is because
+ maybeGetRawHTMLDefinition
, as its name suggests, may
+ return a NULL, in which case we should skip doing any
+ initialization. This, in fact, will correspond to when our fully
+ customized object is already in the cache.
- Those of you who have already been twiddling around with the raw - HTML definition object, you'll be noticing that you're getting an error - when you attempt to retrieve the raw definition object without specifying - a DefinitionID. It is vital to caching (see below) that you make a unique - name for your customized definition, so make up something right now and - things will operate again. -
-@@ -781,6 +775,75 @@ $form->excludes = array('form' => true);
library/HTMLPurifier/ElementDef.php
+ Previously, this tutorial gave some incorrect template code for
+ editing raw definitions, and that template code will now produce the
+ error Due to a documentation error in previous version of HTML
+ Purifier...
Here is how to mechanically transform old-style
+ code into new-style code.
+
+ First, identify all code that edits the raw definition object, and + put it together. Ensure none of this code must be run on every + request; if some sub-part needs to always be run, move it outside + this block. Here is an example below, with the raw definition + object code bolded. +
+ +$config = HTMLPurifier_Config::createDefault(); +$config->set('HTML.DefinitionID', 'enduser-customize.html tutorial'); +$config->set('HTML.DefinitionRev', 1); +$def = $config->getHTMLDefinition(true); +$def->addAttribute('a', 'target', 'Enum#_blank,_self,_target,_top'); +$purifier = new HTMLPurifier($config);+ +
+ Next, replace the raw definition retrieval with a + maybeGetRawHTMLDefinition method call inside an if conditional, and + place the editing code inside that if block. +
+ +$config = HTMLPurifier_Config::createDefault(); +$config->set('HTML.DefinitionID', 'enduser-customize.html tutorial'); +$config->set('HTML.DefinitionRev', 1); +if ($def = $config->maybeGetRawHTMLDefinition()) { + $def->addAttribute('a', 'target', 'Enum#_blank,_self,_target,_top'); +} +$purifier = new HTMLPurifier($config);+ +
+ And you're done! Alternatively, if you're OK with not ever caching + your code, the following will still work and not emit warnings. +
+ +$config = HTMLPurifier_Config::createDefault(); +$def = $config->getHTMLDefinition(true); +$def->addAttribute('a', 'target', 'Enum#_blank,_self,_target,_top'); +$purifier = new HTMLPurifier($config);+ +
+ A slightly less efficient version of this was what was going on with + old versions of HTML Purifier. +
+ +
+ Technical notes: ajh pointed out on in a forum topic that
+ HTML Purifier appeared to be repeatedly writing to the cache even
+ when a cache entry already existed. Investigation lead to the
+ discovery of the following infelicity: caching of customized
+ definitions didn't actually work! The problem was that even though
+ a cache file would be written out at the end of the process, there
+ was no way for HTML Purifier to say, Actually, I've already got a
+ copy of your work, no need to reconfigure your
+ customizations
. This required the API to change: placing
+ all of the customizations to the raw definition object in a
+ conditional which could be skipped.
+