1. sfOutputEscaper.class.php
  2. /**
 * Abstract class that provides an interface for escaping of output.
 *
 * @package    symfony
 * @subpackage view
 * @author     Mike Squire 
 * @version    SVN: $Id: sfOutputEscaper.class.php 21908 2009-09-11 12:06:21Z fabien $
 */
  3. abstract class sfOutputEscaper
  4. {
  5.   /**
  6.    * The value that is to be escaped.
  7.    *
  8.    * @var mixed
  9.    */
  10.   protected $value;
  12.   /**
  13.    * The escaping method that is going to be applied to the value and its
  14.    * children. This is actually the name of a PHP callable.
  15.    *
  16.    * @var string
  17.    */
  18.   protected $escapingMethod;
  20.   static protected $safeClasses = array();
  22.   /**
  23.    * Constructor stores the escaping method and value.
  24.    *
  25.    * Since sfOutputEscaper is an abstract class, instances cannot be created
  26.    * directly but the constructor will be inherited by sub-classes.
  27.    *
  28.    * @param string $escapingMethod  Escaping method
  29.    * @param string $value           Escaping value
  30.    */
  31.   public function __construct($escapingMethod, $value)
  32.   {
  33.     $this->value          = $value;
  34.     $this->escapingMethod = $escapingMethod;
  35.   }
  37.   /**
  38.    * Decorates a PHP variable with something that will escape any data obtained
  39.    * from it.
  40.    *
  41.    * The following cases are dealt with:
  42.    *
  43.    *    - The value is null or false: null or false is returned.
  44.    *    - The value is scalar: the result of applying the escaping method is
  45.    *      returned.
  46.    *    - The value is an array or an object that implements the ArrayAccess
  47.    *      interface: the array is decorated such that accesses to elements yield
  48.    *      an escaped value.
  49.    *    - The value implements the Traversable interface (either an Iterator, an
  50.    *      IteratorAggregate or an internal PHP class that implements
  51.    *      Traversable): decorated much like the array.
  52.    *    - The value is another type of object: decorated such that the result of
  53.    *      method calls is escaped.
  54.    *
  55.    * The escaping method is actually the name of a PHP callable. There are a set
  56.    * of standard escaping methods listed in the escaping helper
  57.    * (EscapingHelper.php).
  58.    *
  59.    * @param  string $escapingMethod  The escaping method (a PHP callable) to apply to the value
  60.    * @param  mixed  $value           The value to escape
  61.    *
  62.    * @return mixed Escaping value
  63.    *
  64.    * @throws InvalidArgumentException If the escaping fails
  65.    */
  66.   public static function escape($escapingMethod, $value)
  67.   {
  68.     if (null === $value)
  69.     {
  70.       return $value;
  71.     }
  73.     // Scalars are anything other than arrays, objects and resources.
  74.     if (is_scalar($value))
  75.     {
  76.       return call_user_func($escapingMethod, $value);
  77.     }
  79.     if (is_array($value))
  80.     {
  81.       return new sfOutputEscaperArrayDecorator($escapingMethod, $value);
  82.     }
  84.     if (is_object($value))
  85.     {
  86.       if ($value instanceof sfOutputEscaper)
  87.       {
  88.         // avoid double decoration
  89.         $copy = clone $value;
  91.         $copy->escapingMethod = $escapingMethod;
  93.         return $copy;
  94.       }
  95.       else if (self::isClassMarkedAsSafe(get_class($value)))
  96.       {
  97.         // the class or one of its children is marked as safe
  98.         // return the unescaped object
  99.         return $value;
  100.       }
  101.       else if ($value instanceof sfOutputEscaperSafe)
  102.       {
  103.         // do not escape objects marked as safe
  104.         // return the original object
  105.         return $value->getValue();
  106.       }
  107.       else if ($value instanceof Traversable)
  108.       {
  109.         return new sfOutputEscaperIteratorDecorator($escapingMethod, $value);
  110.       }
  111.       else
  112.       {
  113.         return new sfOutputEscaperObjectDecorator($escapingMethod, $value);
  114.       }
  115.     }
  117.     // it must be a resource; cannot escape that.
  118.     throw new InvalidArgumentException(sprintf('Unable to escape value "%s".', var_export($value, true)));
  119.   }
  121.   /**
  122.    * Unescapes a value that has been escaped previously with the escape() method.
  123.    *
  124.    * @param  mixed $value The value to unescape
  125.    *
  126.    * @return mixed Unescaped value
  127.    *
  128.    * @throws InvalidArgumentException If the escaping fails
  129.    */
  130.   static public function unescape($value)
  131.   {
  132.     if (null === $value || is_bool($value))
  133.     {
  134.       return $value;
  135.     }
  137.     if (is_scalar($value))
  138.     {
  139.       return html_entity_decode($value, ENT_QUOTES, sfConfig::get('sf_charset'));
  140.     }
  141.     elseif (is_array($value))
  142.     {
  143.       foreach ($value as $name => $v)
  144.       {
  145.         $value[$name] = self::unescape($v);
  146.       }
  148.       return $value;
  149.     }
  150.     elseif (is_object($value))
  151.     {
  152.       return $value instanceof sfOutputEscaper ? $value->getRawValue() : $value;
  153.     }
  155.     return $value;
  156.   }
  158.   /**
  159.    * Returns true if the class if marked as safe.
  160.    *
  161.    * @param  string  $class  A class name
  162.    *
  163.    * @return bool true if the class if safe, false otherwise
  164.    */
  165.   static public function isClassMarkedAsSafe($class)
  166.   {
  167.     if (in_array($class, self::$safeClasses))
  168.     {
  169.       return true;
  170.     }
  172.     foreach (self::$safeClasses as $safeClass)
  173.     {
  174.       if (is_subclass_of($class, $safeClass))
  175.       {
  176.         return true;
  177.       }
  178.     }
  180.     return false;
  181.   }
  183.   /**
  184.    * Marks an array of classes (and all its children) as being safe for output.
  185.    *
  186.    * @param array $classes  An array of class names
  187.    */
  188.   static public function markClassesAsSafe(array $classes)
  189.   {
  190.     self::$safeClasses = array_unique(array_merge(self::$safeClasses, $classes));
  191.   }
  193.   /**
  194.    * Marks a class (and all its children) as being safe for output.
  195.    *
  196.    * @param string $class  A class name
  197.    */
  198.   static public function markClassAsSafe($class)
  199.   {
  200.     self::markClassesAsSafe(array($class));
  201.   }
  203.   /**
  204.    * Returns the raw value associated with this instance.
  205.    *
  206.    * Concrete instances of sfOutputEscaper classes decorate a value which is
  207.    * stored by the constructor. This returns that original, unescaped, value.
  208.    *
  209.    * @return mixed The original value used to construct the decorator
  210.    */
  211.   public function getRawValue()
  212.   {
  213.     return $this->value;
  214.   }
  216.   /**
  217.    * Gets a value from the escaper.
  218.    *
  219.    * @param  string $var  Value to get
  220.    *
  221.    * @return mixed Value
  222.    */
  223.   public function __get($var)
  224.   {
  225.     return $this->escape($this->escapingMethod, $this->value->$var);
  226.   }
  227. }
Debug toolbar