Numerous documentation and test code fixes for HTML Purifier loading

- Improve documentation for stub files
- Synchronize stub files between extras/ and library/
- Remove unnecessary include in function file
- Remove special treatment of Bootstrap
- Improve docs for HTMLPurifier, converted singleton to use static member variables and removed reference
- Add HTMLPurifier.path.php stub file
- Update sample test settings
- Reorganize includes in test files

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

library/HTMLPurifier.auto.php

@@ -2,7 +2,6 @@
 
 /**
  * This is a stub include that automatically configures the include path.
- * @warning This file is currently broken.
  */
 
 set_include_path(dirname(__FILE__) . PATH_SEPARATOR . get_include_path() );

library/HTMLPurifier.autoload.php

@@ -1,11 +1,18 @@
 <?php
 
+/**
+ * @file
+ * Convenience file that registers autoload handler for HTML Purifier.
+ */
+
 if (function_exists('spl_autoload_register')) {
-  spl_autoload_register(array('HTMLPurifier_Bootstrap', 'autoload'));
-  if (function_exists('__autoload')) {
-    // be polite and ensure that userland autoload gets retained
-    spl_autoload_register('__autoload');
-  }
+    spl_autoload_register(array('HTMLPurifier_Bootstrap', 'autoload'));
+    if (function_exists('__autoload')) {
+        // Be polite and ensure that userland autoload gets retained
+        spl_autoload_register('__autoload');
+    }
 } elseif (!function_exists('__autoload')) {
-  function __autoload($class) {return HTMLPurifier_Bootstrap::autoload($class);}
+    function __autoload($class) {
+        return HTMLPurifier_Bootstrap::autoload($class);
+    }
 }

library/HTMLPurifier.func.php

@@ -1,18 +1,20 @@
 <?php
 
 /**
- * Function wrapper for HTML Purifier for quick use.
- * @note This function only includes the library when it is called. While
- *       this is efficient for instances when you only use HTML Purifier
- *       on a few of your pages, it murders bytecode caching. You still
- *       need to add HTML Purifier to your path.
+ * @file
+ * Defines a function wrapper for HTML Purifier for quick use.
  * @note ''HTMLPurifier()'' is NOT the same as ''new HTMLPurifier()''
  */
 
+/**
+ * Purify HTML.
+ * @param $html String HTML to purify
+ * @param $config Configuration to use, can be any value accepted by
+ *        HTMLPurifier_Config::create()
+ */
 function HTMLPurifier($html, $config = null) {
     static $purifier = false;
     if (!$purifier) {
-        require_once 'HTMLPurifier.php';
         $purifier = new HTMLPurifier();
     }
     return $purifier->purify($html, $config);

library/HTMLPurifier.includes.php

@@ -18,15 +18,13 @@
  *      library directory; this is not auto-set.
  */
 
-// Treat this file specially, as it is detached from the rest of the library
-require_once 'HTMLPurifier/Bootstrap.php';
-
 require 'HTMLPurifier.php';
 require 'HTMLPurifier/AttrCollections.php';
 require 'HTMLPurifier/AttrDef.php';
 require 'HTMLPurifier/AttrTransform.php';
 require 'HTMLPurifier/AttrTypes.php';
 require 'HTMLPurifier/AttrValidator.php';
+require 'HTMLPurifier/Bootstrap.php';
 require 'HTMLPurifier/Definition.php';
 require 'HTMLPurifier/CSSDefinition.php';
 require 'HTMLPurifier/ChildDef.php';

library/HTMLPurifier.path.php

@@ -0,0 +1,9 @@
+<?php
+
+/**
+ * @file
+ * Convenience stub file that adds HTML Purifier's library file to the path
+ * without any other side-effects.
+ */
+
+set_include_path(dirname(__FILE__) . PATH_SEPARATOR . get_include_path() );

library/HTMLPurifier.php

@@ -48,25 +48,31 @@
  *          -# Instance: new HTMLPurifier($config)
  *          -# Invocation: purify($html, $config)
  *       These configurations are entirely independent of each other and
- *       are *not* merged.
+ *       are *not* merged (this behavior may change in the future).
  * 
- * @todo We need an easier way to inject strategies, it'll probably end
- *       up getting done through config though.
+ * @todo We need an easier way to inject strategies using the configuration
+ *       object.
  */
 class HTMLPurifier
 {
     
+    /** Version of HTML Purifier */
     public $version = '3.0.0';
     
+    /** Global configuration object */
     public $config;
+    
+    /** Array of HTMLPurifier_Filter objects to run on HTML */
     public $filters = array();
     
+    /** Single instance of HTML Purifier */
+    private static $instance;
+    
     protected $strategy, $generator;
     
     /**
      * Resultant HTMLPurifier_Context of last run purification. Is an array
      * of contexts if the last called method was purifyArray().
-     * @public
      */
     public $context;
     
@@ -107,7 +113,7 @@ class HTMLPurifier
      */
     public function purify($html, $config = null) {
         
-        // todo: make the config merge in, instead of replace
+        // :TODO: make the config merge in, instead of replace
         $config = $config ? HTMLPurifier_Config::create($config) : $this->config;
         
         // implementation is partially environment dependant, partially
@@ -187,18 +193,17 @@ class HTMLPurifier
      * @param $prototype Optional prototype HTMLPurifier instance to
      *                   overload singleton with.
      */
-    public static function &getInstance($prototype = null) {
-        static $htmlpurifier;
-        if (!$htmlpurifier || $prototype) {
+    public static function getInstance($prototype = null) {
+        if (!self::$instance || $prototype) {
             if ($prototype instanceof HTMLPurifier) {
-                $htmlpurifier = $prototype;
+                self::$instance = $prototype;
             } elseif ($prototype) {
-                $htmlpurifier = new HTMLPurifier($prototype);
+                self::$instance = new HTMLPurifier($prototype);
             } else {
-                $htmlpurifier = new HTMLPurifier();
+                self::$instance = new HTMLPurifier();
             }
         }
-        return $htmlpurifier;
+        return self::$instance;
     }
     
 }

library/HTMLPurifier/Bootstrap.php

@@ -20,9 +20,6 @@ if (!defined('PHP_EOL')) {
     }
 }
 
-// :TODO: Might be slow
-if (!class_exists('HTMLPurifier_Bootstrap', false)) {
-
 /**
  * Bootstrap class that contains meta-functionality for HTML Purifier such as
  * the autoload function.
@@ -59,6 +56,3 @@ class HTMLPurifier_Bootstrap
     }
     
 }
-
-}
-