1: <?php
2:
3: /*! @mainpage
4: *
5: * HTML Purifier is an HTML filter that will take an arbitrary snippet of
6: * HTML and rigorously test, validate and filter it into a version that
7: * is safe for output onto webpages. It achieves this by:
8: *
9: * -# Lexing (parsing into tokens) the document,
10: * -# Executing various strategies on the tokens:
11: * -# Removing all elements not in the whitelist,
12: * -# Making the tokens well-formed,
13: * -# Fixing the nesting of the nodes, and
14: * -# Validating attributes of the nodes; and
15: * -# Generating HTML from the purified tokens.
16: *
17: * However, most users will only need to interface with the HTMLPurifier
18: * and HTMLPurifier_Config.
19: */
20:
21: /*
22: HTML Purifier 4.9.3 - Standards Compliant HTML Filtering
23: Copyright (C) 2006-2008 Edward Z. Yang
24:
25: This library is free software; you can redistribute it and/or
26: modify it under the terms of the GNU Lesser General Public
27: License as published by the Free Software Foundation; either
28: version 2.1 of the License, or (at your option) any later version.
29:
30: This library is distributed in the hope that it will be useful,
31: but WITHOUT ANY WARRANTY; without even the implied warranty of
32: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
33: Lesser General Public License for more details.
34:
35: You should have received a copy of the GNU Lesser General Public
36: License along with this library; if not, write to the Free Software
37: Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
38: */
39:
40: /**
41: * Facade that coordinates HTML Purifier's subsystems in order to purify HTML.
42: *
43: * @note There are several points in which configuration can be specified
44: * for HTML Purifier. The precedence of these (from lowest to
45: * highest) is as follows:
46: * -# Instance: new HTMLPurifier($config)
47: * -# Invocation: purify($html, $config)
48: * These configurations are entirely independent of each other and
49: * are *not* merged (this behavior may change in the future).
50: *
51: * @todo We need an easier way to inject strategies using the configuration
52: * object.
53: */
54: class HTMLPurifier
55: {
56:
57: /**
58: * Version of HTML Purifier.
59: * @type string
60: */
61: public $version = '4.9.3';
62:
63: /**
64: * Constant with version of HTML Purifier.
65: */
66: const VERSION = '4.9.3';
67:
68: /**
69: * Global configuration object.
70: * @type HTMLPurifier_Config
71: */
72: public $config;
73:
74: /**
75: * Array of extra filter objects to run on HTML,
76: * for backwards compatibility.
77: * @type HTMLPurifier_Filter[]
78: */
79: private $filters = array();
80:
81: /**
82: * Single instance of HTML Purifier.
83: * @type HTMLPurifier
84: */
85: private static $instance;
86:
87: /**
88: * @type HTMLPurifier_Strategy_Core
89: */
90: protected $strategy;
91:
92: /**
93: * @type HTMLPurifier_Generator
94: */
95: protected $generator;
96:
97: /**
98: * Resultant context of last run purification.
99: * Is an array of contexts if the last called method was purifyArray().
100: * @type HTMLPurifier_Context
101: */
102: public $context;
103:
104: /**
105: * Initializes the purifier.
106: *
107: * @param HTMLPurifier_Config|mixed $config Optional HTMLPurifier_Config object
108: * for all instances of the purifier, if omitted, a default
109: * configuration is supplied (which can be overridden on a
110: * per-use basis).
111: * The parameter can also be any type that
112: * HTMLPurifier_Config::create() supports.
113: */
114: public function __construct($config = null)
115: {
116: $this->config = HTMLPurifier_Config::create($config);
117: $this->strategy = new HTMLPurifier_Strategy_Core();
118: }
119:
120: /**
121: * Adds a filter to process the output. First come first serve
122: *
123: * @param HTMLPurifier_Filter $filter HTMLPurifier_Filter object
124: */
125: public function addFilter($filter)
126: {
127: trigger_error(
128: 'HTMLPurifier->addFilter() is deprecated, use configuration directives' .
129: ' in the Filter namespace or Filter.Custom',
130: E_USER_WARNING
131: );
132: $this->filters[] = $filter;
133: }
134:
135: /**
136: * Filters an HTML snippet/document to be XSS-free and standards-compliant.
137: *
138: * @param string $html String of HTML to purify
139: * @param HTMLPurifier_Config $config Config object for this operation,
140: * if omitted, defaults to the config object specified during this
141: * object's construction. The parameter can also be any type
142: * that HTMLPurifier_Config::create() supports.
143: *
144: * @return string Purified HTML
145: */
146: public function purify($html, $config = null)
147: {
148: // :TODO: make the config merge in, instead of replace
149: $config = $config ? HTMLPurifier_Config::create($config) : $this->config;
150:
151: // implementation is partially environment dependant, partially
152: // configuration dependant
153: $lexer = HTMLPurifier_Lexer::create($config);
154:
155: $context = new HTMLPurifier_Context();
156:
157: // setup HTML generator
158: $this->generator = new HTMLPurifier_Generator($config, $context);
159: $context->register('Generator', $this->generator);
160:
161: // set up global context variables
162: if ($config->get('Core.CollectErrors')) {
163: // may get moved out if other facilities use it
164: $language_factory = HTMLPurifier_LanguageFactory::instance();
165: $language = $language_factory->create($config, $context);
166: $context->register('Locale', $language);
167:
168: $error_collector = new HTMLPurifier_ErrorCollector($context);
169: $context->register('ErrorCollector', $error_collector);
170: }
171:
172: // setup id_accumulator context, necessary due to the fact that
173: // AttrValidator can be called from many places
174: $id_accumulator = HTMLPurifier_IDAccumulator::build($config, $context);
175: $context->register('IDAccumulator', $id_accumulator);
176:
177: $html = HTMLPurifier_Encoder::convertToUTF8($html, $config, $context);
178:
179: // setup filters
180: $filter_flags = $config->getBatch('Filter');
181: $custom_filters = $filter_flags['Custom'];
182: unset($filter_flags['Custom']);
183: $filters = array();
184: foreach ($filter_flags as $filter => $flag) {
185: if (!$flag) {
186: continue;
187: }
188: if (strpos($filter, '.') !== false) {
189: continue;
190: }
191: $class = "HTMLPurifier_Filter_$filter";
192: $filters[] = new $class;
193: }
194: foreach ($custom_filters as $filter) {
195: // maybe "HTMLPurifier_Filter_$filter", but be consistent with AutoFormat
196: $filters[] = $filter;
197: }
198: $filters = array_merge($filters, $this->filters);
199: // maybe prepare(), but later
200:
201: for ($i = 0, $filter_size = count($filters); $i < $filter_size; $i++) {
202: $html = $filters[$i]->preFilter($html, $config, $context);
203: }
204:
205: // purified HTML
206: $html =
207: $this->generator->generateFromTokens(
208: // list of tokens
209: $this->strategy->execute(
210: // list of un-purified tokens
211: $lexer->tokenizeHTML(
212: // un-purified HTML
213: $html,
214: $config,
215: $context
216: ),
217: $config,
218: $context
219: )
220: );
221:
222: for ($i = $filter_size - 1; $i >= 0; $i--) {
223: $html = $filters[$i]->postFilter($html, $config, $context);
224: }
225:
226: $html = HTMLPurifier_Encoder::convertFromUTF8($html, $config, $context);
227: $this->context =& $context;
228: return $html;
229: }
230:
231: /**
232: * Filters an array of HTML snippets
233: *
234: * @param string[] $array_of_html Array of html snippets
235: * @param HTMLPurifier_Config $config Optional config object for this operation.
236: * See HTMLPurifier::purify() for more details.
237: *
238: * @return string[] Array of purified HTML
239: */
240: public function purifyArray($array_of_html, $config = null)
241: {
242: $context_array = array();
243: foreach ($array_of_html as $key => $html) {
244: $array_of_html[$key] = $this->purify($html, $config);
245: $context_array[$key] = $this->context;
246: }
247: $this->context = $context_array;
248: return $array_of_html;
249: }
250:
251: /**
252: * Singleton for enforcing just one HTML Purifier in your system
253: *
254: * @param HTMLPurifier|HTMLPurifier_Config $prototype Optional prototype
255: * HTMLPurifier instance to overload singleton with,
256: * or HTMLPurifier_Config instance to configure the
257: * generated version with.
258: *
259: * @return HTMLPurifier
260: */
261: public static function instance($prototype = null)
262: {
263: if (!self::$instance || $prototype) {
264: if ($prototype instanceof HTMLPurifier) {
265: self::$instance = $prototype;
266: } elseif ($prototype) {
267: self::$instance = new HTMLPurifier($prototype);
268: } else {
269: self::$instance = new HTMLPurifier();
270: }
271: }
272: return self::$instance;
273: }
274:
275: /**
276: * Singleton for enforcing just one HTML Purifier in your system
277: *
278: * @param HTMLPurifier|HTMLPurifier_Config $prototype Optional prototype
279: * HTMLPurifier instance to overload singleton with,
280: * or HTMLPurifier_Config instance to configure the
281: * generated version with.
282: *
283: * @return HTMLPurifier
284: * @note Backwards compatibility, see instance()
285: */
286: public static function getInstance($prototype = null)
287: {
288: return HTMLPurifier::instance($prototype);
289: }
290: }
291:
292: // vim: et sw=4 sts=4
293: