[Sommaire] [Imprimer]

   1  <?php
   2  
   3  /*
   4   * This file is part of the symfony package.
   5   * (c) 2004-2006 Fabien Potencier <fabien.potencier@symfony-project.com>
   6   *
   7   * For the full copyright and license information, please view the LICENSE
   8   * file that was distributed with this source code.
   9   */
  10  
  11  /**
  12   * Abstract class that provides an interface for escaping of output.
  13   *
  14   * @package    symfony
  15   * @subpackage view
  16   * @author     Mike Squire <mike@somosis.co.uk>
  17   * @version    SVN: $Id: sfOutputEscaper.class.php 3232 2007-01-11 20:51:54Z fabien $
  18   */
  19  abstract class sfOutputEscaper
  20  {
  21    /**
  22     * The value that is to be escaped.
  23     *
  24     * @var mixed
  25     */
  26    protected $value;
  27  
  28    /**
  29     * The escaping method that is going to be applied to the value and its
  30     * children. This is actually the name of a PHP function.
  31     *
  32     * @var string
  33     */
  34    protected $escapingMethod;
  35  
  36    /**
  37     * Constructor stores the escaping method and value.
  38     *
  39     * Since sfOutputEscaper is an abstract class, instances cannot be created
  40     * directly but the constructor will be inherited by sub-classes.
  41     *
  42     * @param string Escaping method
  43     * @param string Escaping value
  44     */
  45    public function __construct($escapingMethod, $value)
  46    {
  47      $this->value          = $value;
  48      $this->escapingMethod = $escapingMethod;
  49    }
  50  
  51    /**
  52     * Decorates a PHP variable with something that will escape any data obtained
  53     * from it.
  54     *
  55     * The following cases are dealt with:
  56     *
  57     *    - The value is null or false: null or false is returned.
  58     *    - The value is scalar: the result of applying the escaping method is
  59     *      returned.
  60     *    - The value is an array or an object that implements the ArrayAccess
  61     *      interface: the array is decorated such that accesses to elements yield
  62     *      an escaped value.
  63     *    - The value implements the Traversable interface (either an Iterator, an
  64     *      IteratorAggregate or an internal PHP class that implements
  65     *      Traversable): decorated much like the array.
  66     *    - The value is another type of object: decorated such that the result of
  67     *      method calls is escaped.
  68     *
  69     * The escaping method is actually the name of a PHP function. There are a set
  70     * of standard escaping methods listed in the escaping helper
  71     * (sfEscapingHelper.php).
  72     *
  73     * @param string $escapingMethod the escaping method (a PHP function) to apply to the value
  74     * @param mixed $value the value to escape
  75     * @param mixed the escaped value
  76     *
  77     * @return mixed Escaping value
  78     *
  79     * @throws <b>sfException</b> If the escaping fails
  80     */
  81    public static function escape($escapingMethod, $value)
  82    {
  83      if (is_null($value) || ($value === false) || ($escapingMethod === 'esc_raw'))
  84      {
  85        return $value;
  86      }
  87  
  88      // Scalars are anything other than arrays, objects and resources.
  89      if (is_scalar($value))
  90      {
  91        return call_user_func($escapingMethod, $value);
  92      }
  93  
  94      if (is_array($value))
  95      {
  96        return new sfOutputEscaperArrayDecorator($escapingMethod, $value);
  97      }
  98  
  99      if (is_object($value))
 100      {
 101        if ($value instanceof sfOutputEscaper)
 102        {
 103          // avoid double decoration when passing values from action template to component/partial
 104          $copy = clone $value;
 105  
 106          $copy->escapingMethod = $escapingMethod;
 107  
 108          return $copy;
 109        }
 110        elseif ($value instanceof Traversable)
 111        {
 112          return new sfOutputEscaperIteratorDecorator($escapingMethod, $value);
 113        }
 114        else
 115        {
 116          return new sfOutputEscaperObjectDecorator($escapingMethod, $value);
 117        }
 118      }
 119  
 120      // it must be a resource; cannot escape that.
 121      throw new sfException(sprintf('Unable to escape value "%s"', print_r($value, true)));
 122    }
 123  
 124    /**
 125     * Returns the raw value associated with this instance.
 126     *
 127     * Concrete instances of sfOutputEscaper classes decorate a value which is
 128     * stored by the constructor. This returns that original, unescaped, value.
 129     *
 130     * @return mixed The original value used to construct the decorator
 131     */
 132    public function getRawValue()
 133    {
 134      return $this->value;
 135    }
 136    
 137    /**
 138     * Gets a value from the escaper.
 139     *
 140     * @param string Value to get
 141     *
 142     * @return mixed Value
 143     */
 144    public function __get($var)
 145    {
 146      return $this->escape($this->escapingMethod, $this->value->$var);
 147    }
 148  }