HTMLDefinition.php 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493
  1. <?php
  2. /**
  3. * Definition of the purified HTML that describes allowed children,
  4. * attributes, and many other things.
  5. *
  6. * Conventions:
  7. *
  8. * All member variables that are prefixed with info
  9. * (including the main $info array) are used by HTML Purifier internals
  10. * and should not be directly edited when customizing the HTMLDefinition.
  11. * They can usually be set via configuration directives or custom
  12. * modules.
  13. *
  14. * On the other hand, member variables without the info prefix are used
  15. * internally by the HTMLDefinition and MUST NOT be used by other HTML
  16. * Purifier internals. Many of them, however, are public, and may be
  17. * edited by userspace code to tweak the behavior of HTMLDefinition.
  18. *
  19. * @note This class is inspected by Printer_HTMLDefinition; please
  20. * update that class if things here change.
  21. *
  22. * @warning Directives that change this object's structure must be in
  23. * the HTML or Attr namespace!
  24. */
  25. class HTMLPurifier_HTMLDefinition extends HTMLPurifier_Definition
  26. {
  27. // FULLY-PUBLIC VARIABLES ---------------------------------------------
  28. /**
  29. * Associative array of element names to HTMLPurifier_ElementDef.
  30. * @type HTMLPurifier_ElementDef[]
  31. */
  32. public $info = array();
  33. /**
  34. * Associative array of global attribute name to attribute definition.
  35. * @type array
  36. */
  37. public $info_global_attr = array();
  38. /**
  39. * String name of parent element HTML will be going into.
  40. * @type string
  41. */
  42. public $info_parent = 'div';
  43. /**
  44. * Definition for parent element, allows parent element to be a
  45. * tag that's not allowed inside the HTML fragment.
  46. * @type HTMLPurifier_ElementDef
  47. */
  48. public $info_parent_def;
  49. /**
  50. * String name of element used to wrap inline elements in block context.
  51. * @type string
  52. * @note This is rarely used except for BLOCKQUOTEs in strict mode
  53. */
  54. public $info_block_wrapper = 'p';
  55. /**
  56. * Associative array of deprecated tag name to HTMLPurifier_TagTransform.
  57. * @type array
  58. */
  59. public $info_tag_transform = array();
  60. /**
  61. * Indexed list of HTMLPurifier_AttrTransform to be performed before validation.
  62. * @type HTMLPurifier_AttrTransform[]
  63. */
  64. public $info_attr_transform_pre = array();
  65. /**
  66. * Indexed list of HTMLPurifier_AttrTransform to be performed after validation.
  67. * @type HTMLPurifier_AttrTransform[]
  68. */
  69. public $info_attr_transform_post = array();
  70. /**
  71. * Nested lookup array of content set name (Block, Inline) to
  72. * element name to whether or not it belongs in that content set.
  73. * @type array
  74. */
  75. public $info_content_sets = array();
  76. /**
  77. * Indexed list of HTMLPurifier_Injector to be used.
  78. * @type HTMLPurifier_Injector[]
  79. */
  80. public $info_injector = array();
  81. /**
  82. * Doctype object
  83. * @type HTMLPurifier_Doctype
  84. */
  85. public $doctype;
  86. // RAW CUSTOMIZATION STUFF --------------------------------------------
  87. /**
  88. * Adds a custom attribute to a pre-existing element
  89. * @note This is strictly convenience, and does not have a corresponding
  90. * method in HTMLPurifier_HTMLModule
  91. * @param string $element_name Element name to add attribute to
  92. * @param string $attr_name Name of attribute
  93. * @param mixed $def Attribute definition, can be string or object, see
  94. * HTMLPurifier_AttrTypes for details
  95. */
  96. public function addAttribute($element_name, $attr_name, $def)
  97. {
  98. $module = $this->getAnonymousModule();
  99. if (!isset($module->info[$element_name])) {
  100. $element = $module->addBlankElement($element_name);
  101. } else {
  102. $element = $module->info[$element_name];
  103. }
  104. $element->attr[$attr_name] = $def;
  105. }
  106. /**
  107. * Adds a custom element to your HTML definition
  108. * @see HTMLPurifier_HTMLModule::addElement() for detailed
  109. * parameter and return value descriptions.
  110. */
  111. public function addElement($element_name, $type, $contents, $attr_collections, $attributes = array())
  112. {
  113. $module = $this->getAnonymousModule();
  114. // assume that if the user is calling this, the element
  115. // is safe. This may not be a good idea
  116. $element = $module->addElement($element_name, $type, $contents, $attr_collections, $attributes);
  117. return $element;
  118. }
  119. /**
  120. * Adds a blank element to your HTML definition, for overriding
  121. * existing behavior
  122. * @param string $element_name
  123. * @return HTMLPurifier_ElementDef
  124. * @see HTMLPurifier_HTMLModule::addBlankElement() for detailed
  125. * parameter and return value descriptions.
  126. */
  127. public function addBlankElement($element_name)
  128. {
  129. $module = $this->getAnonymousModule();
  130. $element = $module->addBlankElement($element_name);
  131. return $element;
  132. }
  133. /**
  134. * Retrieves a reference to the anonymous module, so you can
  135. * bust out advanced features without having to make your own
  136. * module.
  137. * @return HTMLPurifier_HTMLModule
  138. */
  139. public function getAnonymousModule()
  140. {
  141. if (!$this->_anonModule) {
  142. $this->_anonModule = new HTMLPurifier_HTMLModule();
  143. $this->_anonModule->name = 'Anonymous';
  144. }
  145. return $this->_anonModule;
  146. }
  147. private $_anonModule = null;
  148. // PUBLIC BUT INTERNAL VARIABLES --------------------------------------
  149. /**
  150. * @type string
  151. */
  152. public $type = 'HTML';
  153. /**
  154. * @type HTMLPurifier_HTMLModuleManager
  155. */
  156. public $manager;
  157. /**
  158. * Performs low-cost, preliminary initialization.
  159. */
  160. public function __construct()
  161. {
  162. $this->manager = new HTMLPurifier_HTMLModuleManager();
  163. }
  164. /**
  165. * @param HTMLPurifier_Config $config
  166. */
  167. protected function doSetup($config)
  168. {
  169. $this->processModules($config);
  170. $this->setupConfigStuff($config);
  171. unset($this->manager);
  172. // cleanup some of the element definitions
  173. foreach ($this->info as $k => $v) {
  174. unset($this->info[$k]->content_model);
  175. unset($this->info[$k]->content_model_type);
  176. }
  177. }
  178. /**
  179. * Extract out the information from the manager
  180. * @param HTMLPurifier_Config $config
  181. */
  182. protected function processModules($config)
  183. {
  184. if ($this->_anonModule) {
  185. // for user specific changes
  186. // this is late-loaded so we don't have to deal with PHP4
  187. // reference wonky-ness
  188. $this->manager->addModule($this->_anonModule);
  189. unset($this->_anonModule);
  190. }
  191. $this->manager->setup($config);
  192. $this->doctype = $this->manager->doctype;
  193. foreach ($this->manager->modules as $module) {
  194. foreach ($module->info_tag_transform as $k => $v) {
  195. if ($v === false) {
  196. unset($this->info_tag_transform[$k]);
  197. } else {
  198. $this->info_tag_transform[$k] = $v;
  199. }
  200. }
  201. foreach ($module->info_attr_transform_pre as $k => $v) {
  202. if ($v === false) {
  203. unset($this->info_attr_transform_pre[$k]);
  204. } else {
  205. $this->info_attr_transform_pre[$k] = $v;
  206. }
  207. }
  208. foreach ($module->info_attr_transform_post as $k => $v) {
  209. if ($v === false) {
  210. unset($this->info_attr_transform_post[$k]);
  211. } else {
  212. $this->info_attr_transform_post[$k] = $v;
  213. }
  214. }
  215. foreach ($module->info_injector as $k => $v) {
  216. if ($v === false) {
  217. unset($this->info_injector[$k]);
  218. } else {
  219. $this->info_injector[$k] = $v;
  220. }
  221. }
  222. }
  223. $this->info = $this->manager->getElements();
  224. $this->info_content_sets = $this->manager->contentSets->lookup;
  225. }
  226. /**
  227. * Sets up stuff based on config. We need a better way of doing this.
  228. * @param HTMLPurifier_Config $config
  229. */
  230. protected function setupConfigStuff($config)
  231. {
  232. $block_wrapper = $config->get('HTML.BlockWrapper');
  233. if (isset($this->info_content_sets['Block'][$block_wrapper])) {
  234. $this->info_block_wrapper = $block_wrapper;
  235. } else {
  236. trigger_error(
  237. 'Cannot use non-block element as block wrapper',
  238. E_USER_ERROR
  239. );
  240. }
  241. $parent = $config->get('HTML.Parent');
  242. $def = $this->manager->getElement($parent, true);
  243. if ($def) {
  244. $this->info_parent = $parent;
  245. $this->info_parent_def = $def;
  246. } else {
  247. trigger_error(
  248. 'Cannot use unrecognized element as parent',
  249. E_USER_ERROR
  250. );
  251. $this->info_parent_def = $this->manager->getElement($this->info_parent, true);
  252. }
  253. // support template text
  254. $support = "(for information on implementing this, see the support forums) ";
  255. // setup allowed elements -----------------------------------------
  256. $allowed_elements = $config->get('HTML.AllowedElements');
  257. $allowed_attributes = $config->get('HTML.AllowedAttributes'); // retrieve early
  258. if (!is_array($allowed_elements) && !is_array($allowed_attributes)) {
  259. $allowed = $config->get('HTML.Allowed');
  260. if (is_string($allowed)) {
  261. list($allowed_elements, $allowed_attributes) = $this->parseTinyMCEAllowedList($allowed);
  262. }
  263. }
  264. if (is_array($allowed_elements)) {
  265. foreach ($this->info as $name => $d) {
  266. if (!isset($allowed_elements[$name])) {
  267. unset($this->info[$name]);
  268. }
  269. unset($allowed_elements[$name]);
  270. }
  271. // emit errors
  272. foreach ($allowed_elements as $element => $d) {
  273. $element = htmlspecialchars($element); // PHP doesn't escape errors, be careful!
  274. trigger_error("Element '$element' is not supported $support", E_USER_WARNING);
  275. }
  276. }
  277. // setup allowed attributes ---------------------------------------
  278. $allowed_attributes_mutable = $allowed_attributes; // by copy!
  279. if (is_array($allowed_attributes)) {
  280. // This actually doesn't do anything, since we went away from
  281. // global attributes. It's possible that userland code uses
  282. // it, but HTMLModuleManager doesn't!
  283. foreach ($this->info_global_attr as $attr => $x) {
  284. $keys = array($attr, "*@$attr", "*.$attr");
  285. $delete = true;
  286. foreach ($keys as $key) {
  287. if ($delete && isset($allowed_attributes[$key])) {
  288. $delete = false;
  289. }
  290. if (isset($allowed_attributes_mutable[$key])) {
  291. unset($allowed_attributes_mutable[$key]);
  292. }
  293. }
  294. if ($delete) {
  295. unset($this->info_global_attr[$attr]);
  296. }
  297. }
  298. foreach ($this->info as $tag => $info) {
  299. foreach ($info->attr as $attr => $x) {
  300. $keys = array("$tag@$attr", $attr, "*@$attr", "$tag.$attr", "*.$attr");
  301. $delete = true;
  302. foreach ($keys as $key) {
  303. if ($delete && isset($allowed_attributes[$key])) {
  304. $delete = false;
  305. }
  306. if (isset($allowed_attributes_mutable[$key])) {
  307. unset($allowed_attributes_mutable[$key]);
  308. }
  309. }
  310. if ($delete) {
  311. if ($this->info[$tag]->attr[$attr]->required) {
  312. trigger_error(
  313. "Required attribute '$attr' in element '$tag' " .
  314. "was not allowed, which means '$tag' will not be allowed either",
  315. E_USER_WARNING
  316. );
  317. }
  318. unset($this->info[$tag]->attr[$attr]);
  319. }
  320. }
  321. }
  322. // emit errors
  323. foreach ($allowed_attributes_mutable as $elattr => $d) {
  324. $bits = preg_split('/[.@]/', $elattr, 2);
  325. $c = count($bits);
  326. switch ($c) {
  327. case 2:
  328. if ($bits[0] !== '*') {
  329. $element = htmlspecialchars($bits[0]);
  330. $attribute = htmlspecialchars($bits[1]);
  331. if (!isset($this->info[$element])) {
  332. trigger_error(
  333. "Cannot allow attribute '$attribute' if element " .
  334. "'$element' is not allowed/supported $support"
  335. );
  336. } else {
  337. trigger_error(
  338. "Attribute '$attribute' in element '$element' not supported $support",
  339. E_USER_WARNING
  340. );
  341. }
  342. break;
  343. }
  344. // otherwise fall through
  345. case 1:
  346. $attribute = htmlspecialchars($bits[0]);
  347. trigger_error(
  348. "Global attribute '$attribute' is not ".
  349. "supported in any elements $support",
  350. E_USER_WARNING
  351. );
  352. break;
  353. }
  354. }
  355. }
  356. // setup forbidden elements ---------------------------------------
  357. $forbidden_elements = $config->get('HTML.ForbiddenElements');
  358. $forbidden_attributes = $config->get('HTML.ForbiddenAttributes');
  359. foreach ($this->info as $tag => $info) {
  360. if (isset($forbidden_elements[$tag])) {
  361. unset($this->info[$tag]);
  362. continue;
  363. }
  364. foreach ($info->attr as $attr => $x) {
  365. if (isset($forbidden_attributes["$tag@$attr"]) ||
  366. isset($forbidden_attributes["*@$attr"]) ||
  367. isset($forbidden_attributes[$attr])
  368. ) {
  369. unset($this->info[$tag]->attr[$attr]);
  370. continue;
  371. } elseif (isset($forbidden_attributes["$tag.$attr"])) { // this segment might get removed eventually
  372. // $tag.$attr are not user supplied, so no worries!
  373. trigger_error(
  374. "Error with $tag.$attr: tag.attr syntax not supported for " .
  375. "HTML.ForbiddenAttributes; use tag@attr instead",
  376. E_USER_WARNING
  377. );
  378. }
  379. }
  380. }
  381. foreach ($forbidden_attributes as $key => $v) {
  382. if (strlen($key) < 2) {
  383. continue;
  384. }
  385. if ($key[0] != '*') {
  386. continue;
  387. }
  388. if ($key[1] == '.') {
  389. trigger_error(
  390. "Error with $key: *.attr syntax not supported for HTML.ForbiddenAttributes; use attr instead",
  391. E_USER_WARNING
  392. );
  393. }
  394. }
  395. // setup injectors -----------------------------------------------------
  396. foreach ($this->info_injector as $i => $injector) {
  397. if ($injector->checkNeeded($config) !== false) {
  398. // remove injector that does not have it's required
  399. // elements/attributes present, and is thus not needed.
  400. unset($this->info_injector[$i]);
  401. }
  402. }
  403. }
  404. /**
  405. * Parses a TinyMCE-flavored Allowed Elements and Attributes list into
  406. * separate lists for processing. Format is element[attr1|attr2],element2...
  407. * @warning Although it's largely drawn from TinyMCE's implementation,
  408. * it is different, and you'll probably have to modify your lists
  409. * @param array $list String list to parse
  410. * @return array
  411. * @todo Give this its own class, probably static interface
  412. */
  413. public function parseTinyMCEAllowedList($list)
  414. {
  415. $list = str_replace(array(' ', "\t"), '', $list);
  416. $elements = array();
  417. $attributes = array();
  418. $chunks = preg_split('/(,|[\n\r]+)/', $list);
  419. foreach ($chunks as $chunk) {
  420. if (empty($chunk)) {
  421. continue;
  422. }
  423. // remove TinyMCE element control characters
  424. if (!strpos($chunk, '[')) {
  425. $element = $chunk;
  426. $attr = false;
  427. } else {
  428. list($element, $attr) = explode('[', $chunk);
  429. }
  430. if ($element !== '*') {
  431. $elements[$element] = true;
  432. }
  433. if (!$attr) {
  434. continue;
  435. }
  436. $attr = substr($attr, 0, strlen($attr) - 1); // remove trailing ]
  437. $attr = explode('|', $attr);
  438. foreach ($attr as $key) {
  439. $attributes["$element.$key"] = true;
  440. }
  441. }
  442. return array($elements, $attributes);
  443. }
  444. }
  445. // vim: et sw=4 sts=4