Merge remote-tracking branch 'upstream/master'

Conflicts:
	doc/html/classRedmatrix_1_1Import_1_1Import-members.html
	doc/html/classRedmatrix_1_1Import_1_1Import.js

7 files changed, 429 insertions, 120 deletions

diff --git a/library/HTMLPurifier/DefinitionCache/Decorator.php b/library/HTMLPurifier/DefinitionCache/Decorator.php
index b0fb6d0cd..b57a51b6c 100644
--- a/library/HTMLPurifier/DefinitionCache/Decorator.php
+++ b/library/HTMLPurifier/DefinitionCache/Decorator.php
@@ -5,58 +5,108 @@ class HTMLPurifier_DefinitionCache_Decorator extends HTMLPurifier_DefinitionCach
 
     /**
      * Cache object we are decorating
+     * @type HTMLPurifier_DefinitionCache
      */
     public $cache;
 
-    public function __construct() {}
+    /**
+     * The name of the decorator
+     * @var string
+     */
+    public $name;
+
+    public function __construct()
+    {
+    }
 
     /**
      * Lazy decorator function
-     * @param $cache Reference to cache object to decorate
+     * @param HTMLPurifier_DefinitionCache $cache Reference to cache object to decorate
+     * @return HTMLPurifier_DefinitionCache_Decorator
      */
-    public function decorate(&$cache) {
+    public function decorate(&$cache)
+    {
         $decorator = $this->copy();
         // reference is necessary for mocks in PHP 4
         $decorator->cache =& $cache;
-        $decorator->type  = $cache->type;
+        $decorator->type = $cache->type;
         return $decorator;
     }
 
     /**
      * Cross-compatible clone substitute
+     * @return HTMLPurifier_DefinitionCache_Decorator
      */
-    public function copy() {
+    public function copy()
+    {
         return new HTMLPurifier_DefinitionCache_Decorator();
     }
 
-    public function add($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function add($def, $config)
+    {
         return $this->cache->add($def, $config);
     }
 
-    public function set($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function set($def, $config)
+    {
         return $this->cache->set($def, $config);
     }
 
-    public function replace($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function replace($def, $config)
+    {
         return $this->cache->replace($def, $config);
     }
 
-    public function get($config) {
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function get($config)
+    {
         return $this->cache->get($config);
     }
 
-    public function remove($config) {
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function remove($config)
+    {
         return $this->cache->remove($config);
     }
 
-    public function flush($config) {
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function flush($config)
+    {
         return $this->cache->flush($config);
     }
 
-    public function cleanup($config) {
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function cleanup($config)
+    {
         return $this->cache->cleanup($config);
     }
-
 }
 
 // vim: et sw=4 sts=4
diff --git a/library/HTMLPurifier/DefinitionCache/Decorator/Cleanup.php b/library/HTMLPurifier/DefinitionCache/Decorator/Cleanup.php
index d4cc35c4b..4991777ce 100644
--- a/library/HTMLPurifier/DefinitionCache/Decorator/Cleanup.php
+++ b/library/HTMLPurifier/DefinitionCache/Decorator/Cleanup.php
@@ -4,40 +4,75 @@
  * Definition cache decorator class that cleans up the cache
  * whenever there is a cache miss.
  */
-class HTMLPurifier_DefinitionCache_Decorator_Cleanup extends
-      HTMLPurifier_DefinitionCache_Decorator
+class HTMLPurifier_DefinitionCache_Decorator_Cleanup extends HTMLPurifier_DefinitionCache_Decorator
 {
-
+    /**
+     * @type string
+     */
     public $name = 'Cleanup';
 
-    public function copy() {
+    /**
+     * @return HTMLPurifier_DefinitionCache_Decorator_Cleanup
+     */
+    public function copy()
+    {
         return new HTMLPurifier_DefinitionCache_Decorator_Cleanup();
     }
 
-    public function add($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function add($def, $config)
+    {
         $status = parent::add($def, $config);
-        if (!$status) parent::cleanup($config);
+        if (!$status) {
+            parent::cleanup($config);
+        }
         return $status;
     }
 
-    public function set($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function set($def, $config)
+    {
         $status = parent::set($def, $config);
-        if (!$status) parent::cleanup($config);
+        if (!$status) {
+            parent::cleanup($config);
+        }
         return $status;
     }
 
-    public function replace($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function replace($def, $config)
+    {
         $status = parent::replace($def, $config);
-        if (!$status) parent::cleanup($config);
+        if (!$status) {
+            parent::cleanup($config);
+        }
         return $status;
     }
 
-    public function get($config) {
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function get($config)
+    {
         $ret = parent::get($config);
-        if (!$ret) parent::cleanup($config);
+        if (!$ret) {
+            parent::cleanup($config);
+        }
         return $ret;
     }
-
 }
 
 // vim: et sw=4 sts=4
diff --git a/library/HTMLPurifier/DefinitionCache/Decorator/Memory.php b/library/HTMLPurifier/DefinitionCache/Decorator/Memory.php
index 18f16d32b..d529dce48 100644
--- a/library/HTMLPurifier/DefinitionCache/Decorator/Memory.php
+++ b/library/HTMLPurifier/DefinitionCache/Decorator/Memory.php
@@ -5,42 +5,81 @@
  * 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
+class HTMLPurifier_DefinitionCache_Decorator_Memory extends HTMLPurifier_DefinitionCache_Decorator
 {
-
+    /**
+     * @type array
+     */
     protected $definitions;
+
+    /**
+     * @type string
+     */
     public $name = 'Memory';
 
-    public function copy() {
+    /**
+     * @return HTMLPurifier_DefinitionCache_Decorator_Memory
+     */
+    public function copy()
+    {
         return new HTMLPurifier_DefinitionCache_Decorator_Memory();
     }
 
-    public function add($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function add($def, $config)
+    {
         $status = parent::add($def, $config);
-        if ($status) $this->definitions[$this->generateKey($config)] = $def;
+        if ($status) {
+            $this->definitions[$this->generateKey($config)] = $def;
+        }
         return $status;
     }
 
-    public function set($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function set($def, $config)
+    {
         $status = parent::set($def, $config);
-        if ($status) $this->definitions[$this->generateKey($config)] = $def;
+        if ($status) {
+            $this->definitions[$this->generateKey($config)] = $def;
+        }
         return $status;
     }
 
-    public function replace($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function replace($def, $config)
+    {
         $status = parent::replace($def, $config);
-        if ($status) $this->definitions[$this->generateKey($config)] = $def;
+        if ($status) {
+            $this->definitions[$this->generateKey($config)] = $def;
+        }
         return $status;
     }
 
-    public function get($config) {
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function get($config)
+    {
         $key = $this->generateKey($config);
-        if (isset($this->definitions[$key])) return $this->definitions[$key];
+        if (isset($this->definitions[$key])) {
+            return $this->definitions[$key];
+        }
         $this->definitions[$key] = parent::get($config);
         return $this->definitions[$key];
     }
-
 }
 
 // vim: et sw=4 sts=4
diff --git a/library/HTMLPurifier/DefinitionCache/Decorator/Template.php.in b/library/HTMLPurifier/DefinitionCache/Decorator/Template.php.in
index 21a8fcfda..b1fec8d36 100644
--- a/library/HTMLPurifier/DefinitionCache/Decorator/Template.php.in
+++ b/library/HTMLPurifier/DefinitionCache/Decorator/Template.php.in
@@ -5,43 +5,78 @@ require_once 'HTMLPurifier/DefinitionCache/Decorator.php';
 /**
  * Definition cache decorator template.
  */
-class HTMLPurifier_DefinitionCache_Decorator_Template extends
-      HTMLPurifier_DefinitionCache_Decorator
+class HTMLPurifier_DefinitionCache_Decorator_Template extends HTMLPurifier_DefinitionCache_Decorator
 {
 
-    var $name = 'Template'; // replace this
+    /**
+     * @type string
+     */
+    public $name = 'Template'; // replace this
 
-    function copy() {
+    public function copy()
+    {
         // replace class name with yours
         return new HTMLPurifier_DefinitionCache_Decorator_Template();
     }
 
     // remove methods you don't need
 
-    function add($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function add($def, $config)
+    {
         return parent::add($def, $config);
     }
 
-    function set($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function set($def, $config)
+    {
         return parent::set($def, $config);
     }
 
-    function replace($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function replace($def, $config)
+    {
         return parent::replace($def, $config);
     }
 
-    function get($config) {
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function get($config)
+    {
         return parent::get($config);
     }
 
-    function flush() {
-        return parent::flush();
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function flush($config)
+    {
+        return parent::flush($config);
     }
 
-    function cleanup($config) {
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return mixed
+     */
+    public function cleanup($config)
+    {
         return parent::cleanup($config);
     }
-
 }
 
 // vim: et sw=4 sts=4
diff --git a/library/HTMLPurifier/DefinitionCache/Null.php b/library/HTMLPurifier/DefinitionCache/Null.php
index 41d97e734..d9a75ce22 100644
--- a/library/HTMLPurifier/DefinitionCache/Null.php
+++ b/library/HTMLPurifier/DefinitionCache/Null.php
@@ -6,34 +6,71 @@
 class HTMLPurifier_DefinitionCache_Null extends HTMLPurifier_DefinitionCache
 {
 
-    public function add($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return bool
+     */
+    public function add($def, $config)
+    {
         return false;
     }
 
-    public function set($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return bool
+     */
+    public function set($def, $config)
+    {
         return false;
     }
 
-    public function replace($def, $config) {
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return bool
+     */
+    public function replace($def, $config)
+    {
         return false;
     }
 
-    public function remove($config) {
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return bool
+     */
+    public function remove($config)
+    {
         return false;
     }
 
-    public function get($config) {
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return bool
+     */
+    public function get($config)
+    {
         return false;
     }
 
-    public function flush($config) {
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return bool
+     */
+    public function flush($config)
+    {
         return false;
     }
 
-    public function cleanup($config) {
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return bool
+     */
+    public function cleanup($config)
+    {
         return false;
     }
-
 }
 
 // vim: et sw=4 sts=4
diff --git a/library/HTMLPurifier/DefinitionCache/Serializer.php b/library/HTMLPurifier/DefinitionCache/Serializer.php
index 7a6aa93f0..ecacb88fe 100644
--- a/library/HTMLPurifier/DefinitionCache/Serializer.php
+++ b/library/HTMLPurifier/DefinitionCache/Serializer.php
@@ -1,83 +1,160 @@
 <?php
 
-class HTMLPurifier_DefinitionCache_Serializer extends
-      HTMLPurifier_DefinitionCache
+class HTMLPurifier_DefinitionCache_Serializer extends HTMLPurifier_DefinitionCache
 {
 
-    public function add($def, $config) {
-        if (!$this->checkDefType($def)) return;
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return int|bool
+     */
+    public function add($def, $config)
+    {
+        if (!$this->checkDefType($def)) {
+            return;
+        }
         $file = $this->generateFilePath($config);
-        if (file_exists($file)) return false;
-        if (!$this->_prepareDir($config)) return false;
-        return $this->_write($file, serialize($def));
+        if (file_exists($file)) {
+            return false;
+        }
+        if (!$this->_prepareDir($config)) {
+            return false;
+        }
+        return $this->_write($file, serialize($def), $config);
     }
 
-    public function set($def, $config) {
-        if (!$this->checkDefType($def)) return;
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return int|bool
+     */
+    public function set($def, $config)
+    {
+        if (!$this->checkDefType($def)) {
+            return;
+        }
         $file = $this->generateFilePath($config);
-        if (!$this->_prepareDir($config)) return false;
-        return $this->_write($file, serialize($def));
+        if (!$this->_prepareDir($config)) {
+            return false;
+        }
+        return $this->_write($file, serialize($def), $config);
     }
 
-    public function replace($def, $config) {
-        if (!$this->checkDefType($def)) return;
+    /**
+     * @param HTMLPurifier_Definition $def
+     * @param HTMLPurifier_Config $config
+     * @return int|bool
+     */
+    public function replace($def, $config)
+    {
+        if (!$this->checkDefType($def)) {
+            return;
+        }
         $file = $this->generateFilePath($config);
-        if (!file_exists($file)) return false;
-        if (!$this->_prepareDir($config)) return false;
-        return $this->_write($file, serialize($def));
+        if (!file_exists($file)) {
+            return false;
+        }
+        if (!$this->_prepareDir($config)) {
+            return false;
+        }
+        return $this->_write($file, serialize($def), $config);
     }
 
-    public function get($config) {
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return bool|HTMLPurifier_Config
+     */
+    public function get($config)
+    {
         $file = $this->generateFilePath($config);
-        if (!file_exists($file)) return false;
+        if (!file_exists($file)) {
+            return false;
+        }
         return unserialize(file_get_contents($file));
     }
 
-    public function remove($config) {
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return bool
+     */
+    public function remove($config)
+    {
         $file = $this->generateFilePath($config);
-        if (!file_exists($file)) return false;
+        if (!file_exists($file)) {
+            return false;
+        }
         return unlink($file);
     }
 
-    public function flush($config) {
-        if (!$this->_prepareDir($config)) return false;
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return bool
+     */
+    public function flush($config)
+    {
+        if (!$this->_prepareDir($config)) {
+            return false;
+        }
         $dir = $this->generateDirectoryPath($config);
-        $dh  = opendir($dir);
+        $dh = opendir($dir);
         while (false !== ($filename = readdir($dh))) {
-            if (empty($filename)) continue;
-            if ($filename[0] === '.') continue;
+            if (empty($filename)) {
+                continue;
+            }
+            if ($filename[0] === '.') {
+                continue;
+            }
             unlink($dir . '/' . $filename);
         }
     }
 
-    public function cleanup($config) {
-        if (!$this->_prepareDir($config)) return false;
+    /**
+     * @param HTMLPurifier_Config $config
+     * @return bool
+     */
+    public function cleanup($config)
+    {
+        if (!$this->_prepareDir($config)) {
+            return false;
+        }
         $dir = $this->generateDirectoryPath($config);
-        $dh  = opendir($dir);
+        $dh = opendir($dir);
         while (false !== ($filename = readdir($dh))) {
-            if (empty($filename)) continue;
-            if ($filename[0] === '.') continue;
+            if (empty($filename)) {
+                continue;
+            }
+            if ($filename[0] === '.') {
+                continue;
+            }
             $key = substr($filename, 0, strlen($filename) - 4);
-            if ($this->isOld($key, $config)) unlink($dir . '/' . $filename);
+            if ($this->isOld($key, $config)) {
+                unlink($dir . '/' . $filename);
+            }
         }
     }
 
     /**
      * Generates the file path to the serial file corresponding to
      * the configuration and definition name
+     * @param HTMLPurifier_Config $config
+     * @return string
      * @todo Make protected
      */
-    public function generateFilePath($config) {
+    public function generateFilePath($config)
+    {
         $key = $this->generateKey($config);
         return $this->generateDirectoryPath($config) . '/' . $key . '.ser';
     }
 
     /**
      * Generates the path to the directory contain this cache's serial files
+     * @param HTMLPurifier_Config $config
+     * @return string
      * @note No trailing slash
      * @todo Make protected
      */
-    public function generateDirectoryPath($config) {
+    public function generateDirectoryPath($config)
+    {
         $base = $this->generateBaseDirectoryPath($config);
         return $base . '/' . $this->type;
     }
@@ -85,9 +162,12 @@ class HTMLPurifier_DefinitionCache_Serializer extends
     /**
      * Generates path to base directory that contains all definition type
      * serials
+     * @param HTMLPurifier_Config $config
+     * @return mixed|string
      * @todo Make protected
      */
-    public function generateBaseDirectoryPath($config) {
+    public function generateBaseDirectoryPath($config)
+    {
         $base = $config->get('Cache.SerializerPath');
         $base = is_null($base) ? HTMLPURIFIER_PREFIX . '/HTMLPurifier/DefinitionCache/Serializer' : $base;
         return $base;
@@ -95,34 +175,54 @@ class HTMLPurifier_DefinitionCache_Serializer extends
 
     /**
      * Convenience wrapper function for file_put_contents
-     * @param $file File name to write to
-     * @param $data Data to write into file
-     * @return Number of bytes written if success, or false if failure.
+     * @param string $file File name to write to
+     * @param string $data Data to write into file
+     * @param HTMLPurifier_Config $config
+     * @return int|bool Number of bytes written if success, or false if failure.
      */
-    private function _write($file, $data) {
-        return file_put_contents($file, $data);
+    private function _write($file, $data, $config)
+    {
+        $result = file_put_contents($file, $data);
+        if ($result !== false) {
+            // set permissions of the new file (no execute)
+            $chmod = $config->get('Cache.SerializerPermissions');
+            if (!$chmod) {
+                $chmod = 0644; // invalid config or simpletest
+            }
+            $chmod = $chmod & 0666;
+            chmod($file, $chmod);
+        }
+        return $result;
     }
 
     /**
      * Prepares the directory that this type stores the serials in
-     * @return True if successful
+     * @param HTMLPurifier_Config $config
+     * @return bool True if successful
      */
-    private function _prepareDir($config) {
+    private function _prepareDir($config)
+    {
         $directory = $this->generateDirectoryPath($config);
+        $chmod = $config->get('Cache.SerializerPermissions');
+        if (!$chmod) {
+            $chmod = 0755; // invalid config or simpletest
+        }
         if (!is_dir($directory)) {
             $base = $this->generateBaseDirectoryPath($config);
             if (!is_dir($base)) {
-                trigger_error('Base directory '.$base.' does not exist,
+                trigger_error(
+                    'Base directory ' . $base . ' does not exist,
                     please create or change using %Cache.SerializerPath',
-                    E_USER_WARNING);
+                    E_USER_WARNING
+                );
                 return false;
-            } elseif (!$this->_testPermissions($base)) {
+            } elseif (!$this->_testPermissions($base, $chmod)) {
                 return false;
             }
-            $old = umask(0022); // disable group and world writes
-            mkdir($directory);
+            $old = umask(0000);
+            mkdir($directory, $chmod);
             umask($old);
-        } elseif (!$this->_testPermissions($directory)) {
+        } elseif (!$this->_testPermissions($directory, $chmod)) {
             return false;
         }
         return true;
@@ -131,42 +231,55 @@ class HTMLPurifier_DefinitionCache_Serializer extends
     /**
      * Tests permissions on a directory and throws out friendly
      * error messages and attempts to chmod it itself if possible
+     * @param string $dir Directory path
+     * @param int $chmod Permissions
+     * @return bool True if directory is writable
      */
-    private function _testPermissions($dir) {
+    private function _testPermissions($dir, $chmod)
+    {
         // early abort, if it is writable, everything is hunky-dory
-        if (is_writable($dir)) return true;
+        if (is_writable($dir)) {
+            return true;
+        }
         if (!is_dir($dir)) {
             // generally, you'll want to handle this beforehand
             // so a more specific error message can be given
-            trigger_error('Directory '.$dir.' does not exist',
-                E_USER_WARNING);
+            trigger_error(
+                'Directory ' . $dir . ' does not exist',
+                E_USER_WARNING
+            );
             return false;
         }
         if (function_exists('posix_getuid')) {
             // POSIX system, we can give more specific advice
             if (fileowner($dir) === posix_getuid()) {
                 // we can chmod it ourselves
-                chmod($dir, 0755);
-                return true;
+                $chmod = $chmod | 0700;
+                if (chmod($dir, $chmod)) {
+                    return true;
+                }
             } elseif (filegroup($dir) === posix_getgid()) {
-                $chmod = '775';
+                $chmod = $chmod | 0070;
             } else {
                 // PHP's probably running as nobody, so we'll
                 // need to give global permissions
-                $chmod = '777';
+                $chmod = $chmod | 0777;
             }
-            trigger_error('Directory '.$dir.' not writable, '.
-                'please chmod to ' . $chmod,
-                E_USER_WARNING);
+            trigger_error(
+                'Directory ' . $dir . ' not writable, ' .
+                'please chmod to ' . decoct($chmod),
+                E_USER_WARNING
+            );
         } else {
             // generic error message
-            trigger_error('Directory '.$dir.' not writable, '.
+            trigger_error(
+                'Directory ' . $dir . ' not writable, ' .
                 'please alter file permissions',
-                E_USER_WARNING);
+                E_USER_WARNING
+            );
         }
         return false;
     }
-
 }
 
 // vim: et sw=4 sts=4
diff --git a/library/HTMLPurifier/DefinitionCache/Serializer/README b/library/HTMLPurifier/DefinitionCache/Serializer/README
index 2e35c1c3d..2e35c1c3d 100644..100755
--- a/library/HTMLPurifier/DefinitionCache/Serializer/README
+++ b/library/HTMLPurifier/DefinitionCache/Serializer/README