[1.7.0] Add DefinitionCache decorators, implement Memory decorator

- Move serialization responsibility to Config
- Create DefinitionCacheFactory
- Implement Null definition cache

git-svn-id: http://htmlpurifier.org/svnroot/htmlpurifier/trunk@1117 48356398-32a2-884e-a903-53898d9a118a

library/HTMLPurifier/Config.php

@@ -6,7 +6,7 @@ require_once 'HTMLPurifier/ConfigSchema.php';
 require_once 'HTMLPurifier/HTMLDefinition.php';
 require_once 'HTMLPurifier/CSSDefinition.php';
 require_once 'HTMLPurifier/Doctype.php';
-require_once 'HTMLPurifier/DefinitionCache.php';
+require_once 'HTMLPurifier/DefinitionCacheFactory.php';
 
 // accomodations for versions earlier than 4.3.10 and 5.0.2
 // borrowed from PHP_Compat, LGPL licensed, by Aidan Lister <aidan@php.net>
@@ -76,6 +76,12 @@ class HTMLPurifier_Config
      */
     var $autoFinalize = true;
     
+    /**
+     * Namespace indexed array of serials for specific namespaces (see
+     * getSerial for more info).
+     */
+    var $serials = array();
+    
     /**
      * @param $definition HTMLPurifier_ConfigSchema that defines what directives
      *                    are allowed.
@@ -149,6 +155,18 @@ class HTMLPurifier_Config
         return $this->conf[$namespace];
     }
     
+    /**
+     * Returns a md5 signature of a segment of the configuration object
+     * that uniquely identifies that particular configuration
+     * @param $namespace Namespace to get serial for
+     */
+    function getBatchSerial($namespace) {
+        if (empty($this->serials[$namespace])) {
+            $this->serials[$namespace] = md5(serialize($this->getBatch($namespace)));
+        }
+        return $this->serials[$namespace];
+    }
+    
     /**
      * Retrieves all directives, organized by namespace
      */
@@ -210,6 +228,8 @@ class HTMLPurifier_Config
         if ($namespace == 'HTML' || $namespace == 'CSS') {
             $this->definitions[$namespace] = null;
         }
+        
+        $this->serials[$namespace] = false;
     }
     
     /**
@@ -235,7 +255,8 @@ class HTMLPurifier_Config
      */
     function &getDefinition($type, $raw = false) {
         if (!$this->finalized && $this->autoFinalize) $this->finalize();
-        $cache = HTMLPurifier_DefinitionCache::create($type, $this);
+        $factory = HTMLPurifier_DefinitionCacheFactory::instance();
+        $cache = $factory->create($type, $this);
         if (!$raw) {
             // see if we can quickly supply a definition
             if (!empty($this->definitions[$type])) {

library/HTMLPurifier/DefinitionCache.php

@@ -1,11 +1,13 @@
 <?php
 
 require_once 'HTMLPurifier/DefinitionCache/Serializer.php';
+require_once 'HTMLPurifier/DefinitionCache/Null.php';
+
+require_once 'HTMLPurifier/DefinitionCache/Decorator.php';
 
 /**
  * Abstract class representing Definition cache managers that implements
  * useful common methods and is a factory.
- * @note The configuration object is transformed into the key used by the cache
  * @todo Get some sort of versioning variable so the library can easily
  *       invalidate the cache with a new version
  * @todo Make the test runner cache aware and allow the user to easily
@@ -33,9 +35,9 @@ class HTMLPurifier_DefinitionCache
      * @param Instance of HTMLPurifier_Config
      */
     function generateKey($config) {
-        $version  = $config->version;
-        $revision = $config->revision;
-        return $version . '-' . $revision . '-' . md5(serialize($config->getBatch($this->type)));
+        return $config->version . '-' . // possibly replace with function calls
+               $config->revision . '-' .
+               $config->getBatchSerial($this->type);
     }
     
     /**
@@ -52,17 +54,6 @@ class HTMLPurifier_DefinitionCache
         return true;
     }
     
-    /**
-     * Factory method that creates a cache object based on configuration
-     * @param $name Name of definitions handled by cache
-     * @param $config Instance of HTMLPurifier_Config
-     */
-    function create($name, $config) {
-        // only one implementation as for right now, $config will
-        // be used to determine implementation
-        return new HTMLPurifier_DefinitionCache_Serializer($name);
-    }
-    
     /**
      * Checks if a definition's type jives with the cache's type
      * @note Throws an error on failure

library/HTMLPurifier/DefinitionCache/Decorator.php

@@ -0,0 +1,62 @@
+<?php
+
+require_once 'HTMLPurifier/DefinitionCache.php';
+
+require_once 'HTMLPurifier/DefinitionCache/Decorator/Memory.php';
+
+class HTMLPurifier_DefinitionCache_Decorator extends HTMLPurifier_DefinitionCache
+{
+    
+    /**
+     * Cache object we are decorating
+     */
+    var $cache;
+    
+    function HTMLPurifier_DefinitionCache_Decorator() {}
+    
+    /**
+     * Lazy decorator function
+     * @param $cache Reference to cache object to decorate
+     */
+    function decorate(&$cache) {
+        $decorator = $this->copy();
+        // reference is necessary for mocks in PHP 4
+        $decorator->cache =& $cache;
+        $decorator->type  = $cache->type;
+        return $decorator;
+    }
+    
+    /**
+     * Cross-compatible clone substitute
+     */
+    function copy() {
+        return new HTMLPurifier_DefinitionCache_Decorator();
+    }
+    
+    function add($def, $config) {
+        return $this->cache->add($def, $config);
+    }
+    
+    function set($def, $config) {
+        return $this->cache->set($def, $config);
+    }
+    
+    function replace($def, $config) {
+        return $this->cache->replace($def, $config);
+    }
+    
+    function get($config) {
+        return $this->cache->get($config);
+    }
+    
+    function flush() {
+        return $this->cache->flush();
+    }
+    
+    function cleanup($config) {
+        return $this->cache->cleanup($config);
+    }
+    
+}
+
+?>

library/HTMLPurifier/DefinitionCache/Decorator/Memory.php

@@ -0,0 +1,47 @@
+<?php
+
+require_once 'HTMLPurifier/DefinitionCache/Decorator.php';
+
+/**
+ * Definition cache decorator class that saves all cache retrievals
+ * to PHP's memory; good for unit tests or circumstances where 
+ * there are lots of configuration objects floating around.
+ */
+class HTMLPurifier_DefinitionCache_Decorator_Memory extends
+      HTMLPurifier_DefinitionCache_Decorator
+{
+    
+    var $definitions;
+    
+    function copy() {
+        return new HTMLPurifier_DefinitionCache_Decorator_Memory();
+    }
+    
+    function add($def, $config) {
+        $status = parent::add($def, $config);
+        if ($status) $this->definitions[$this->generateKey($config)] = $def;
+        return $status;
+    }
+    
+    function set($def, $config) {
+        $status = parent::set($def, $config);
+        if ($status) $this->definitions[$this->generateKey($config)] = $def;
+        return $status;
+    }
+    
+    function replace($def, $config) {
+        $status = parent::replace($def, $config);
+        if ($status) $this->definitions[$this->generateKey($config)] = $def;
+        return $status;
+    }
+    
+    function get($config) {
+        $key = $this->generateKey($config);
+        if (isset($this->definitions[$key])) return $this->definitions[$key];
+        $this->definitions[$key] = parent::get($config);
+        return $this->definitions[$key];
+    }
+    
+}
+
+?>

library/HTMLPurifier/DefinitionCache/Decorator/Template.php.in

@@ -0,0 +1,46 @@
+<?php
+
+require_once 'HTMLPurifier/DefinitionCache/Decorator.php';
+
+/**
+ * Definition cache decorator template.
+ */
+class HTMLPurifier_DefinitionCache_Decorator_Template extends
+      HTMLPurifier_DefinitionCache_Decorator
+{
+    
+    // must be defined!!!
+    
+    function copy() {
+        return new HTMLPurifier_DefinitionCache_Decorator_Template();
+    }
+    
+    // remove methods you don't need
+    
+    function add($def, $config) {
+        return parent::add($def, $config);
+    }
+    
+    function set($def, $config) {
+        return parent::set($def, $config);
+    }
+    
+    function replace($def, $config) {
+        return parent::replace($def, $config);
+    }
+    
+    function get($config) {
+        return parent::get($config);
+    }
+    
+    function flush() {
+        return parent::flush();
+    }
+    
+    function cleanup($config) {
+        return parent::cleanup($config);
+    }
+    
+}
+
+?>

library/HTMLPurifier/DefinitionCache/Null.php

@@ -0,0 +1,37 @@
+<?php
+
+require_once 'HTMLPurifier/DefinitionCache.php';
+
+/**
+ * Null cache object to use when no caching is on.
+ */
+class HTMLPurifier_DefinitionCache_Null extends HTMLPurifier_DefinitionCache
+{
+    
+    function add($def, $config) {
+        return false;
+    }
+    
+    function set($def, $config) {
+        return false;
+    }
+    
+    function replace($def, $config) {
+        return false;
+    }
+    
+    function get($config) {
+        return false;
+    }
+    
+    function flush() {
+        return false;
+    }
+    
+    function cleanup($config) {
+        return false;
+    }
+    
+}
+
+?>

library/HTMLPurifier/DefinitionCacheFactory.php

@@ -0,0 +1,82 @@
+<?php
+
+require_once 'HTMLPurifier/DefinitionCache.php';
+
+HTMLPurifier_ConfigSchema::define(
+    'Core', 'DefinitionCache', 'Serializer', 'string/null', '
+This directive defines which method to use when caching definitions,
+the complex data-type that makes HTML Purifier tick. Set to null
+to disable caching (not recommended, as you will see a definite
+performance degradation). This directive has been available since 1.7.0.
+');
+
+HTMLPurifier_ConfigSchema::defineAllowedValues(
+    'Core', 'DefinitionCache', array('Serializer')
+);
+
+
+/**
+ * Responsible for creating definition caches.
+ */
+class HTMLPurifier_DefinitionCacheFactory
+{
+    
+    var $caches = array('Serializer' => array());
+    var $decorators = array();
+    
+    /**
+     * Retrieves an instance of global definition cache factory.
+     * @static
+     */
+    function &instance($prototype = null) {
+        static $instance;
+        if ($prototype !== null) {
+            $instance = $prototype;
+        } elseif ($instance === null || $prototype === true) {
+            $instance = new HTMLPurifier_DefinitionCacheFactory();
+        }
+        return $instance;
+    }
+    
+    /**
+     * Factory method that creates a cache object based on configuration
+     * @param $name Name of definitions handled by cache
+     * @param $config Instance of HTMLPurifier_Config
+     */
+    function &create($type, $config) {
+        // only one implementation as for right now, $config will
+        // be used to determine implementation
+        $method = $config->get('Core', 'DefinitionCache');
+        if ($method === null) {
+            $null = new HTMLPurifier_DefinitionCache_Null($type);
+            return $null;
+        }
+        if (!empty($this->caches[$method][$type])) {
+            return $this->caches[$method][$type];
+        }
+        $cache = new HTMLPurifier_DefinitionCache_Serializer($type);
+        foreach ($this->decorators as $decorator) {
+            $new_cache = $decorator->decorate($cache);
+            // prevent infinite recursion in PHP 4
+            unset($cache);
+            $cache = $new_cache;
+        }
+        $this->caches[$method][$type] = $cache;
+        return $this->caches[$method][$type];
+    }
+    
+    /**
+     * Registers a decorator to add to all new cache objects
+     * @param 
+     */
+    function addDecorator($decorator) {
+        if (is_string($decorator)) {
+            $class = "HTMLPurifier_DefinitionCache_Decorator_$decorator";
+            $decorator = new $class;
+        }
+        $this->decorators[] = $decorator;
+    }
+    
+}
+
+?>