[2.1.0] Friendly error messages for when injector needs a tag that's not allowed added

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

NEWS

@@ -13,6 +13,8 @@ NEWS ( CHANGELOG and HISTORY )                                     HTMLPurifier
 ! With %Core.AggressivelyFixLt, <3 and similar emoticons no longer
   trigger HTML removal in PHP5 (DOMLex). This directive is not necessary
   for PHP4 (DirectLex).
+- AutoFormatters emit friendly error messages if tags or attributes they
+  need are not allowed
 
 2.0.2, unknown release date
 (none)

library/HTMLPurifier/Injector.php

@@ -8,6 +8,11 @@
 class HTMLPurifier_Injector
 {
     
+    /**
+     * Advisory name of injector, this is for friendly error messages
+     */
+    var $name;
+    
     /**
      * Amount of tokens the injector needs to skip + 1. Because
      * the decrement is the first thing that happens, this needs to
@@ -40,16 +45,37 @@ class HTMLPurifier_Injector
     var $inputIndex;
     
     /**
-     * Prepares the injector by giving it the config and context objects,
+     * Array of elements and attributes this injector creates and therefore
-     * so that important variables can be extracted and not passed via
+     * need to be allowed by the definition. Takes form of
-     * parameter constantly. Remember: always instantiate a new injector
+     * array('element' => array('attr', 'attr2'), 'element2')
-     * when handling a set of HTML.
+     */
+    var $needed = array();
+    
+    /**
+     * Prepares the injector by giving it the config and context objects:
+     * this allows references to important variables to be made within
+     * the injector. This function also checks if the HTML environment
+     * will work with the Injector: if p tags are not allowed, the
+     * Auto-Paragraphing injector should not be enabled.
+     * @param $config Instance of HTMLPurifier_Config
+     * @param $context Instance of HTMLPurifier_Context
+     * @return Boolean false if success, string of missing needed element/attribute if failure
      */
     function prepare($config, &$context) {
         $this->htmlDefinition = $config->getHTMLDefinition();
+        // perform $needed checks
+        foreach ($this->needed as $element => $attributes) {
+            if (is_int($element)) $element = $attributes;
+            if (!isset($this->htmlDefinition->info[$element])) return $element;
+            if (!is_array($attributes)) continue;
+            foreach ($attributes as $name) {
+                if (!isset($this->htmlDefinition->info[$element]->attr[$name])) return "$element.$name";
+            }
+        }
         $this->currentNesting =& $context->get('CurrentNesting');
         $this->inputTokens    =& $context->get('InputTokens');
         $this->inputIndex     =& $context->get('InputIndex');
+        return false;
     }
     
     /**

library/HTMLPurifier/Injector/AutoParagraph.php

@@ -15,6 +15,11 @@ HTMLPurifier_ConfigSchema::define(
       block elements in nodes that allow paragraph tags</li>
   <li>There are double newlines in paragraph tags</li>
 </ul>
+<p>
+  <code>p</code> tags must be allowed for this directive to take effect.
+  We do not use <code>br</code> tags for paragraphing, as that is
+  semantically incorrect.
+</p>
 <p>
   This directive has been available since 2.0.1.
 </p>
@@ -27,6 +32,9 @@ HTMLPurifier_ConfigSchema::define(
 class HTMLPurifier_Injector_AutoParagraph extends HTMLPurifier_Injector
 {
     
+    var $name = 'AutoParagraph';
+    var $needed = array('p');
+    
     function _pStart() {
         $par = new HTMLPurifier_Token_Start('p');
         $par->armor['MakeWellFormed_TagClosedError'] = true;

library/HTMLPurifier/Injector/Linkify.php

@@ -6,7 +6,8 @@ HTMLPurifier_ConfigSchema::define(
     'AutoFormat', 'Linkify', false, 'bool', '
 <p>
   This directive turns on linkification, auto-linking http, ftp and
-  https URLs. This directive has been available since 2.0.1.
+  https URLs. <code>a</code> tags with the <code>href</code> attribute
+  must be allowed. This directive has been available since 2.0.1.
 </p>
 ');
 
@@ -16,6 +17,9 @@ HTMLPurifier_ConfigSchema::define(
 class HTMLPurifier_Injector_Linkify extends HTMLPurifier_Injector
 {
     
+    var $name = 'Linkify';
+    var $needed = array('a' => array('href'));
+    
     function handleText(&$token) {
         if (!$this->allowsElement('a')) return;
         

library/HTMLPurifier/Injector/PurifierLinkify.php

@@ -6,8 +6,9 @@ HTMLPurifier_ConfigSchema::define(
     'AutoFormat', 'PurifierLinkify', false, 'bool', '
 <p>
   Internal auto-formatter that converts configuration directives in
-  syntax <a>%Namespace.Directive</a> to links. This directive has been available
+  syntax <a>%Namespace.Directive</a> to links. <code>a</code> tags
-  since 2.0.1.
+  with the <code>href</code> attribute must be allowed.
+  This directive has been available since 2.0.1.
 </p>
 ');
 
@@ -27,11 +28,13 @@ HTMLPurifier_ConfigSchema::define(
 class HTMLPurifier_Injector_PurifierLinkify extends HTMLPurifier_Injector
 {
     
+    var $name = 'PurifierLinkify';
     var $docURL;
+    var $needed = array('a' => array('href'));
     
     function prepare($config, &$context) {
-        parent::prepare($config, $context);
         $this->docURL = $config->get('AutoFormatParam', 'PurifierLinkifyDocURL');
+        return parent::prepare($config, $context);
     }
     
     function handleText(&$token) {

library/HTMLPurifier/Strategy/MakeWellFormed.php

@@ -67,7 +67,8 @@ class HTMLPurifier_Strategy_MakeWellFormed extends HTMLPurifier_Strategy
         unset($injectors['Custom']); // special case
         foreach ($injectors as $injector => $b) {
             $injector = "HTMLPurifier_Injector_$injector";
-            if ($b) $this->injectors[] = new $injector;
+            if (!$b) continue;
+            $this->injectors[] = new $injector;
         }
         foreach ($custom_injectors as $injector) {
             if (is_string($injector)) {
@@ -87,7 +88,11 @@ class HTMLPurifier_Strategy_MakeWellFormed extends HTMLPurifier_Strategy
         // give the injectors references to the definition and context
         // variables for performance reasons
         foreach ($this->injectors as $i => $x) {
-            $this->injectors[$i]->prepare($config, $context);
+            $error = $this->injectors[$i]->prepare($config, $context);
+            if (!$error) continue;
+            list($injector) = array_splice($this->injectors, $i, 1);
+            $name = $injector->name;
+            trigger_error("Cannot enable $name injector because $error is not allowed", E_USER_WARNING);
         }
         
         // -- end INJECTOR --

tests/HTMLPurifier/Injector/AutoParagraphTest.php

@@ -249,5 +249,10 @@ Par2',
         );
     }
     
+    function testNeeded() {
+        $this->expectError('Cannot enable AutoParagraph injector because p is not allowed');
+        $this->assertResult('<b>foobar</b>', true, array('AutoFormat.AutoParagraph' => true, 'HTML.Allowed' => 'b'));
+    }
+    
 }
 

tests/HTMLPurifier/Injector/LinkifyTest.php

@@ -34,5 +34,10 @@ class HTMLPurifier_Injector_LinkifyTest extends HTMLPurifier_InjectorHarness
         
     }
     
+    function testNeeded() {
+        $this->expectError('Cannot enable Linkify injector because a is not allowed');
+        $this->assertResult('http://example.com/', true, array('AutoFormat.Linkify' => true, 'HTML.Allowed' => 'b'));
+    }
+    
 }
 

tests/HTMLPurifier/Injector/PurifierLinkifyTest.php

@@ -38,5 +38,10 @@ class HTMLPurifier_Injector_PurifierLinkifyTest extends HTMLPurifier_InjectorHar
         
     }
     
+    function testNeeded() {
+        $this->expectError('Cannot enable PurifierLinkify injector because a is not allowed');
+        $this->assertResult('%Namespace.Directive', true, array('AutoFormat.PurifierLinkify' => true, 'HTML.Allowed' => 'b'));
+    }
+    
 }