library/htmlspecialchars.inc.php

   1 <?php
   2 /*
   3 Copyright © 2011 Boyd Stephen Smith Jr.
   4
   5 Copyright license terms appear at the end of this file.
   6 */
   7
   8 /*
   9 This function uses htmlspecialchars() to escape a PHP string for use as
  10 (part of) an HTML / XML text node (in DOM terms).
  11
  12 It only escapes a few special chars: the ampersand (&) and both the left-
  13 pointing angle bracket (<) and the right-pointing angle bracket (>), since
  14 these are the only characters that are special in a text node.  Minimal quoting
  15 is preferred because it produces smaller and more easily human-readable output.
  16
  17 Some characters simply cannot appear in valid XML documents, even
  18 as entities but, this function does not attempt to handle them.
  19
  20 NOTE: Attribute values are NOT text nodes, and require additional escaping.
  21 */
  22 function text($text) {
  23         return htmlspecialchars($text, ENT_NOQUOTES);
  24 }
  25
  26 /*
  27 This function uses htmlspecialchars() to escape a PHP string for use as
  28 part of an HTML / XML attribute value.  It does not surround the string in
  29 single- or double-quote characters as is required for XML.
  30
  31 This does the maximal quoting handled by htmlspecialchars()
  32
  33 Some characters simply cannot appear in valid XML documents, even
  34 as entities but, this function does not attempt to handle them.
  35
  36 NOTE: This can be used as a "generic" HTML escape since it does maximal
  37 quoting.  However, some HTML and XML contexts (CDATA) don't provide escape
  38 mechanisms.  Also, further pre- or post-escaping might need to be done when
  39 embdedded other languages (like JavaScript) inside HTML / XML documents.
  40 */
  41 function attr($text) {
  42         return htmlspecialchars($text, ENT_QUOTES);
  43 }
  44
  45 /*
  46 This function is a compatibility replacement for the out function removed from
  47 the CDR Admin framework.
  48 */
  49 function out($text) {
  50         return attr($text);
  51 }
  52
  53 /*
  54 Don't call this function.  You don't see this function.  This function doesn't
  55 exist.
  56
  57 TODO: Hide this function so it can be called from this file but not from PHP
  58 that includes / requires this file.  Either that, or write reasonable
  59 documentation and clean up the name.
  60 */
  61 function hsc_private_xl_or_warn($key) {
  62         if (function_exists('xl')) {
  63                 return xl($key);
  64         } else {
  65                 trigger_error(
  66                         'Translation via xl() was requested, but the xl()'
  67                         . ' function is not defined, yet.',
  68                         E_USER_WARNING
  69                 );
  70                 return $key;
  71         }
  72 }
  73
  74 /*
  75 Translate via xl() and then escape via text().
  76 */
  77 function xlt($key) {
  78         return text(hsc_private_xl_or_warn($key));
  79 }
  80
  81 /*
  82 Translate via xl() and then escape via attr().
  83 */
  84 function xla($key) {
  85         return attr(hsc_private_xl_or_warn($key));
  86 }
  87
  88 return; // Stop include / require from going any further (non-PHP)
  89 ?>
  90 This file is free software: you can redistribute it and/or modify
  91 it under the terms of the GNU General Public License as published by
  92 the Free Software Foundation, either version 3 of the License, or
  93 (at your option) any later version.
  94
  95 This file is distributed in the hope that it will be useful,
  96 but WITHOUT ANY WARRANTY; without even the implied warranty of
  97 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  98 GNU General Public License for more details.
  99
 100 You should have received a copy of the GNU General Public License
 101 along with this program.  If not, see <http://www.gnu.org/licenses/>.