HTML.php 8.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344
  1. <?php
  2. /**
  3. * HTML helper class. Provides generic methods for generating various HTML
  4. * tags and making output HTML safe.
  5. *
  6. * @package Kohana
  7. * @category Helpers
  8. * @author Kohana Team
  9. * @copyright (c) Kohana Team
  10. * @license https://koseven.ga/LICENSE.md
  11. */
  12. class Kohana_HTML {
  13. /**
  14. * @var array preferred order of attributes
  15. */
  16. public static $attribute_order = [
  17. 'action',
  18. 'method',
  19. 'type',
  20. 'id',
  21. 'name',
  22. 'value',
  23. 'href',
  24. 'src',
  25. 'width',
  26. 'height',
  27. 'cols',
  28. 'rows',
  29. 'size',
  30. 'maxlength',
  31. 'rel',
  32. 'media',
  33. 'accept-charset',
  34. 'accept',
  35. 'tabindex',
  36. 'accesskey',
  37. 'alt',
  38. 'title',
  39. 'class',
  40. 'style',
  41. 'selected',
  42. 'checked',
  43. 'readonly',
  44. 'disabled',
  45. ];
  46. /**
  47. * @var boolean use strict XHTML mode?
  48. */
  49. public static $strict = TRUE;
  50. /**
  51. * @var boolean automatically target external URLs to a new window?
  52. */
  53. public static $windowed_urls = FALSE;
  54. /**
  55. * Convert special characters to HTML entities. All untrusted content
  56. * should be passed through this method to prevent XSS injections.
  57. *
  58. * echo HTML::chars($username);
  59. *
  60. * @param string $value string to convert
  61. * @param boolean $double_encode encode existing entities
  62. * @return string
  63. */
  64. public static function chars($value, $double_encode = TRUE)
  65. {
  66. return htmlspecialchars( (string) $value, ENT_QUOTES, Kohana::$charset, $double_encode);
  67. }
  68. /**
  69. * Convert all applicable characters to HTML entities. All characters
  70. * that cannot be represented in HTML with the current character set
  71. * will be converted to entities.
  72. *
  73. * echo HTML::entities($username);
  74. *
  75. * @param string $value string to convert
  76. * @param boolean $double_encode encode existing entities
  77. * @return string
  78. */
  79. public static function entities($value, $double_encode = TRUE)
  80. {
  81. return htmlentities( (string) $value, ENT_QUOTES, Kohana::$charset, $double_encode);
  82. }
  83. /**
  84. * Create HTML link anchors. Note that the title is not escaped, to allow
  85. * HTML elements within links (images, etc).
  86. *
  87. * echo HTML::anchor('/user/profile', 'My Profile');
  88. *
  89. * @param string $uri URL or URI string
  90. * @param string $title link text
  91. * @param array $attributes HTML anchor attributes
  92. * @param mixed $protocol protocol to pass to URL::base()
  93. * @param boolean $index include the index page
  94. * @return string
  95. * @uses URL::base
  96. * @uses URL::site
  97. * @uses HTML::attributes
  98. */
  99. public static function anchor($uri, $title = NULL, array $attributes = NULL, $protocol = NULL, $index = TRUE)
  100. {
  101. if ($title === NULL)
  102. {
  103. // Use the URI as the title
  104. $title = $uri;
  105. }
  106. if ($uri === '')
  107. {
  108. // Only use the base URL
  109. $uri = URL::base($protocol, $index);
  110. }
  111. else
  112. {
  113. if (strpos($uri, '://') !== FALSE OR strncmp($uri, '//', 2) == 0)
  114. {
  115. if (HTML::$windowed_urls === TRUE AND empty($attributes['target']))
  116. {
  117. // Make the link open in a new window
  118. $attributes['target'] = '_blank';
  119. }
  120. }
  121. elseif ($uri[0] !== '#' AND $uri[0] !== '?')
  122. {
  123. // Make the URI absolute for non-fragment and non-query anchors
  124. $uri = URL::site($uri, $protocol, $index);
  125. }
  126. }
  127. // Add the sanitized link to the attributes
  128. $attributes['href'] = $uri;
  129. return '<a'.HTML::attributes($attributes).'>'.$title.'</a>';
  130. }
  131. /**
  132. * Creates an HTML anchor to a file. Note that the title is not escaped,
  133. * to allow HTML elements within links (images, etc).
  134. *
  135. * echo HTML::file_anchor('media/doc/user_guide.pdf', 'User Guide');
  136. *
  137. * @param string $file name of file to link to
  138. * @param string $title link text
  139. * @param array $attributes HTML anchor attributes
  140. * @param mixed $protocol protocol to pass to URL::base()
  141. * @param boolean $index include the index page
  142. * @return string
  143. * @uses URL::base
  144. * @uses HTML::attributes
  145. */
  146. public static function file_anchor($file, $title = NULL, array $attributes = NULL, $protocol = NULL, $index = FALSE)
  147. {
  148. if ($title === NULL)
  149. {
  150. // Use the file name as the title
  151. $title = basename($file);
  152. }
  153. // Add the file link to the attributes
  154. $attributes['href'] = URL::site($file, $protocol, $index);
  155. return '<a'.HTML::attributes($attributes).'>'.$title.'</a>';
  156. }
  157. /**
  158. * Creates an email (mailto:) anchor. Note that the title is not escaped,
  159. * to allow HTML elements within links (images, etc).
  160. *
  161. * echo HTML::mailto($address);
  162. *
  163. * @param string $email email address to send to
  164. * @param string $title link text
  165. * @param array $attributes HTML anchor attributes
  166. * @return string
  167. * @uses HTML::attributes
  168. */
  169. public static function mailto($email, $title = NULL, array $attributes = NULL)
  170. {
  171. if ($title === NULL)
  172. {
  173. // Use the email address as the title
  174. $title = $email;
  175. }
  176. return '<a href="&#109;&#097;&#105;&#108;&#116;&#111;&#058;'.$email.'"'.HTML::attributes($attributes).'>'.$title.'</a>';
  177. }
  178. /**
  179. * Creates a style sheet link element.
  180. *
  181. * echo HTML::style('media/css/screen.css');
  182. *
  183. * @param string $file file name
  184. * @param array $attributes default attributes
  185. * @param mixed $protocol protocol to pass to URL::base()
  186. * @param boolean $index include the index page
  187. * @return string
  188. * @uses URL::base
  189. * @uses HTML::attributes
  190. */
  191. public static function style($file, array $attributes = NULL, $protocol = NULL, $index = FALSE)
  192. {
  193. if (strpos($file, '://') === FALSE AND strncmp($file, '//', 2))
  194. {
  195. // Add the base URL
  196. $file = URL::site($file, $protocol, $index);
  197. }
  198. // Set the stylesheet link
  199. $attributes['href'] = $file;
  200. // Set the stylesheet rel
  201. $attributes['rel'] = empty($attributes['rel']) ? 'stylesheet' : $attributes['rel'];
  202. // Set the stylesheet type
  203. $attributes['type'] = 'text/css';
  204. return '<link'.HTML::attributes($attributes).' />';
  205. }
  206. /**
  207. * Creates a script link.
  208. *
  209. * echo HTML::script('media/js/jquery.min.js');
  210. *
  211. * @param string $file file name
  212. * @param array $attributes default attributes
  213. * @param mixed $protocol protocol to pass to URL::base()
  214. * @param boolean $index include the index page
  215. * @return string
  216. * @uses URL::base
  217. * @uses HTML::attributes
  218. */
  219. public static function script($file, array $attributes = NULL, $protocol = NULL, $index = FALSE)
  220. {
  221. if (strpos($file, '://') === FALSE AND strncmp($file, '//', 2))
  222. {
  223. // Add the base URL
  224. $file = URL::site($file, $protocol, $index);
  225. }
  226. // Set the script link
  227. $attributes['src'] = $file;
  228. // Set the script type
  229. $attributes['type'] = 'text/javascript';
  230. return '<script'.HTML::attributes($attributes).'></script>';
  231. }
  232. /**
  233. * Creates a image link.
  234. *
  235. * echo HTML::image('media/img/logo.png', array('alt' => 'My Company'));
  236. *
  237. * @param string $file file name
  238. * @param array $attributes default attributes
  239. * @param mixed $protocol protocol to pass to URL::base()
  240. * @param boolean $index include the index page
  241. * @return string
  242. * @uses URL::base
  243. * @uses HTML::attributes
  244. */
  245. public static function image($file, array $attributes = NULL, $protocol = NULL, $index = FALSE)
  246. {
  247. if (strpos($file, '://') === FALSE AND strncmp($file, '//', 2) AND strncmp($file, 'data:', 5))
  248. {
  249. // Add the base URL
  250. $file = URL::site($file, $protocol, $index);
  251. }
  252. // Add the image link
  253. $attributes['src'] = $file;
  254. return '<img'.HTML::attributes($attributes).' />';
  255. }
  256. /**
  257. * Compiles an array of HTML attributes into an attribute string.
  258. * Attributes will be sorted using HTML::$attribute_order for consistency.
  259. *
  260. * echo '<div'.HTML::attributes($attrs).'>'.$content.'</div>';
  261. *
  262. * @param array $attributes attribute list
  263. * @return string
  264. */
  265. public static function attributes(array $attributes = NULL)
  266. {
  267. if (empty($attributes))
  268. return '';
  269. $sorted = [];
  270. foreach (HTML::$attribute_order as $key)
  271. {
  272. if (isset($attributes[$key]))
  273. {
  274. // Add the attribute to the sorted list
  275. $sorted[$key] = $attributes[$key];
  276. }
  277. }
  278. // Combine the sorted attributes
  279. $attributes = $sorted + $attributes;
  280. $compiled = '';
  281. foreach ($attributes as $key => $value)
  282. {
  283. if ($value === NULL)
  284. {
  285. // Skip attributes that have NULL values
  286. continue;
  287. }
  288. if (is_int($key))
  289. {
  290. // Assume non-associative keys are mirrored attributes
  291. $key = $value;
  292. if ( ! HTML::$strict)
  293. {
  294. // Just use a key
  295. $value = FALSE;
  296. }
  297. }
  298. // Add the attribute key
  299. $compiled .= ' '.$key;
  300. if ($value OR HTML::$strict)
  301. {
  302. // Add the attribute value
  303. $compiled .= '="'.HTML::chars($value).'"';
  304. }
  305. }
  306. return $compiled;
  307. }
  308. }