[1.4.0] YouTube preservation code added to the core by adding HTMLPurifier_Filter hierarchy.

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

NEWS

@@ -19,6 +19,9 @@ NEWS ( CHANGELOG and HISTORY )                                     HTMLPurifier
   characters while %Core.Encoding is set to a non-UTF-8 encoding.
 ! Support for configuration directive aliases added
 ! Config object can now be instantiated from ini files
+! YouTube preservation code added to the core, with two lines of code
+  you can add it as a filter to your code. See smoketests/preserveYouTube.php
+  for sample code.
 - Replaced version check with functionality check for DOM (thanks Stephen
   Khoo)
 . Added smoketest 'all.php', which loads all other smoketests via frames

TODO

@@ -8,7 +8,6 @@ TODO List
 ==========================
 
 1.4 release
- # Add hooks for custom behavior (for instance, YouTube preservation)
  - Aggressive caching
  ? Configuration profiles: sets of directives that get set with one func call
 

docs/enduser-youtube.html

@@ -172,9 +172,10 @@ introduced after it has finished.</p>
 
 <h2>Future plans</h2>
 
-<p>It would probably be a good idea if this code was added to the core
-library. Look out for the inclusion of this into the core as a decorator
-or the like.</p>
+<p>This functionality is part of the core library, using the
+HTMLPurifier_Filter class to acheive the desired effect. Our implementation
+is slightly different, and this page will be updated to reflect that
+once 1.4.0 is released.</p>
 
 </body>
 </html>

library/HTMLPurifier.php

@@ -67,6 +67,7 @@ class HTMLPurifier
     var $version = '1.3.2';
     
     var $config;
+    var $filters;
     
     var $lexer, $strategy, $generator;
     
@@ -94,6 +95,14 @@ class HTMLPurifier
         
     }
     
+    /**
+     * Adds a filter to process the output. First come first serve
+     * @param $filter HTMLPurifier_Filter object
+     */
+    function addFilter($filter) {
+        $this->filters[] = $filter;
+    }
+    
     /**
      * Filters an HTML snippet/document to be XSS-free and standards-compliant.
      * 
@@ -111,6 +120,10 @@ class HTMLPurifier
         $context = new HTMLPurifier_Context();
         $html = HTMLPurifier_Encoder::convertToUTF8($html, $config, $context);
         
+        for ($i = 0, $size = count($this->filters); $i < $size; $i++) {
+            $html = $this->filters[$i]->preFilter($html, $config, $context);
+        }
+        
         // purified HTML
         $html = 
             $this->generator->generateFromTokens(
@@ -126,6 +139,10 @@ class HTMLPurifier
                 $config, $context
             );
         
+        for ($i = $size - 1; $i >= 0; $i--) {
+            $html = $this->filters[$i]->postFilter($html, $config, $context);
+        }
+        
         $html = HTMLPurifier_Encoder::convertFromUTF8($html, $config, $context);
         $this->context =& $context;
         return $html;

library/HTMLPurifier/Filter.php

@@ -0,0 +1,39 @@
+<?php
+
+/**
+ * Represents a pre or post processing filter on HTML Purifier's output
+ * 
+ * Sometimes, a little ad-hoc fixing of HTML has to be done before
+ * it gets sent through HTML Purifier: you can use filters to acheive
+ * this effect. For instance, YouTube videos can be preserved using
+ * this manner. You could have used a decorator for this task, but
+ * PHP's support for them is not terribly robust, so we're going
+ * to just loop through the filters.
+ * 
+ * Filters should be exited first in, last out. If there are three filters,
+ * named 1, 2 and 3, the order of execution should go 1->preFilter,
+ * 2->preFilter, 3->preFilter, purify, 3->postFilter, 2->postFilter,
+ * 1->postFilter.
+ */
+
+class HTMLPurifier_Filter
+{
+    
+    /**
+     * Name of the filter for identification purposes
+     */
+    var $name;
+    
+    /**
+     * Pre-processor function, handles HTML before HTML Purifier 
+     */
+    function preFilter($html, $config, &$context) {}
+    
+    /**
+     * Post-processor function, handles HTML after HTML Purifier
+     */
+    function postFilter($html, $config, &$context) {}
+    
+}
+
+?>

library/HTMLPurifier/Filter/YouTube.php

@@ -0,0 +1,34 @@
+<?php
+
+require_once 'HTMLPurifier/Filter.php';
+
+class HTMLPurifier_Filter_YouTube extends HTMLPurifier_Filter
+{
+    
+    var $name = 'YouTube preservation';
+    
+    function preFilter($html, $config, &$context) {
+        $pre_regex = '#<object[^>]+>.+?'.
+            'http://www.youtube.com/v/([A-Za-z0-9]+).+?</object>#';
+        $pre_replace = '<span class="youtube-embed">\1</span>';
+        return preg_replace($pre_regex, $pre_replace, $html);
+    }
+    
+    function postFilter($html, $config, &$context) {
+        $post_regex = '#<span class="youtube-embed">([A-Za-z0-9]+)</span>#';
+        $post_replace = '<object width="425" height="350" '.
+            'data="http://www.youtube.com/v/\1">'.
+            '<param name="movie" value="http://www.youtube.com/v/\1"></param>'.
+            '<param name="wmode" value="transparent"></param>'.
+            '<!--[if IE]>'.
+            '<embed src="http://www.youtube.com/v/\1"'.
+            'type="application/x-shockwave-flash"'.
+            'wmode="transparent" width="425" height="350" />'.
+            '<![endif]-->'.
+            '</object>';
+        return preg_replace($post_regex, $post_replace, $html);
+    }
+    
+}
+
+?>

smoketests/preserveYouTube.php

@@ -15,34 +15,13 @@ echo '<?xml version="1.0" encoding="UTF-8" ?>';
 <h1>HTML Purifier Preserve YouTube Smoketest</h1>
 <?php
 
-class HTMLPurifierX_PreserveYouTube extends HTMLPurifier
-{
-    function purify($html, $config = null) {
-        $pre_regex = '#<object[^>]+>.+?'.
-            'http://www.youtube.com/v/([A-Za-z0-9]+).+?</object>#';
-        $pre_replace = '<span class="youtube-embed">\1</span>';
-        $html = preg_replace($pre_regex, $pre_replace, $html);
-        $html = parent::purify($html, $config);
-        $post_regex = '#<span class="youtube-embed">([A-Za-z0-9]+)</span>#';
-        $post_replace = '<object width="425" height="350" '.
-            'data="http://www.youtube.com/v/\1">'.
-            '<param name="movie" value="http://www.youtube.com/v/\1"></param>'.
-            '<param name="wmode" value="transparent"></param>'.
-            '<!--[if IE]>'.
-            '<embed src="http://www.youtube.com/v/\1"'.
-            'type="application/x-shockwave-flash"'.
-            'wmode="transparent" width="425" height="350" />'.
-            '<![endif]-->'.
-            '</object>';
-        $html = preg_replace($post_regex, $post_replace, $html);
-        return $html;
-    }
-}
-
 $string = '<object width="425" height="350"><param name="movie" value="http://www.youtube.com/v/JzqumbhfxRo"></param><param name="wmode" value="transparent"></param><embed src="http://www.youtube.com/v/JzqumbhfxRo" type="application/x-shockwave-flash" wmode="transparent" width="425" height="350"></embed></object>';
 
 $regular_purifier = new HTMLPurifier();
-$youtube_purifier = new HTMLPurifierX_PreserveYouTube();
+
+$youtube_purifier = new HTMLPurifier();
+require_once 'HTMLPurifier/Filter/YouTube.php';
+$youtube_purifier->addFilter(new HTMLPurifier_Filter_YouTube());
 
 ?>
 <h2>Unpurified</h2>