initial commit

lib/symfony/view/escaper/sfOutputEscaper.class.php

@@ -0,0 +1,148 @@
+<?php
+
+/*
+ * This file is part of the symfony package.
+ * (c) 2004-2006 Fabien Potencier <fabien.potencier@symfony-project.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/**
+ * Abstract class that provides an interface for escaping of output.
+ *
+ * @package    symfony
+ * @subpackage view
+ * @author     Mike Squire <mike@somosis.co.uk>
+ * @version    SVN: $Id: sfOutputEscaper.class.php 4262 2007-06-19 12:27:58Z fabien $
+ */
+abstract class sfOutputEscaper
+{
+  /**
+   * The value that is to be escaped.
+   *
+   * @var mixed
+   */
+  protected $value;
+
+  /**
+   * The escaping method that is going to be applied to the value and its
+   * children. This is actually the name of a PHP function.
+   *
+   * @var string
+   */
+  protected $escapingMethod;
+
+  /**
+   * Constructor stores the escaping method and value.
+   *
+   * Since sfOutputEscaper is an abstract class, instances cannot be created
+   * directly but the constructor will be inherited by sub-classes.
+   *
+   * @param string Escaping method
+   * @param string Escaping value
+   */
+  public function __construct($escapingMethod, $value)
+  {
+    $this->value          = $value;
+    $this->escapingMethod = $escapingMethod;
+  }
+
+  /**
+   * Decorates a PHP variable with something that will escape any data obtained
+   * from it.
+   *
+   * The following cases are dealt with:
+   *
+   *    - The value is null or false: null or false is returned.
+   *    - The value is scalar: the result of applying the escaping method is
+   *      returned.
+   *    - The value is an array or an object that implements the ArrayAccess
+   *      interface: the array is decorated such that accesses to elements yield
+   *      an escaped value.
+   *    - The value implements the Traversable interface (either an Iterator, an
+   *      IteratorAggregate or an internal PHP class that implements
+   *      Traversable): decorated much like the array.
+   *    - The value is another type of object: decorated such that the result of
+   *      method calls is escaped.
+   *
+   * The escaping method is actually the name of a PHP callable. There are a set
+   * of standard escaping methods listed in the escaping helper
+   * (EscapingHelper.php).
+   *
+   * @param string $escapingMethod the escaping method (a PHP function) to apply to the value
+   * @param mixed $value the value to escape
+   * @param mixed the escaped value
+   *
+   * @return mixed Escaping value
+   *
+   * @throws <b>sfException</b> If the escaping fails
+   */
+  public static function escape($escapingMethod, $value)
+  {
+    if (is_null($value) || ($value === false) || ($escapingMethod === 'esc_raw'))
+    {
+      return $value;
+    }
+
+    // Scalars are anything other than arrays, objects and resources.
+    if (is_scalar($value))
+    {
+      return call_user_func($escapingMethod, $value);
+    }
+
+    if (is_array($value))
+    {
+      return new sfOutputEscaperArrayDecorator($escapingMethod, $value);
+    }
+
+    if (is_object($value))
+    {
+      if ($value instanceof sfOutputEscaper)
+      {
+        // avoid double decoration when passing values from action template to component/partial
+        $copy = clone $value;
+
+        $copy->escapingMethod = $escapingMethod;
+
+        return $copy;
+      }
+      elseif ($value instanceof Traversable)
+      {
+        return new sfOutputEscaperIteratorDecorator($escapingMethod, $value);
+      }
+      else
+      {
+        return new sfOutputEscaperObjectDecorator($escapingMethod, $value);
+      }
+    }
+
+    // it must be a resource; cannot escape that.
+    throw new sfException(sprintf('Unable to escape value "%s"', print_r($value, true)));
+  }
+
+  /**
+   * Returns the raw value associated with this instance.
+   *
+   * Concrete instances of sfOutputEscaper classes decorate a value which is
+   * stored by the constructor. This returns that original, unescaped, value.
+   *
+   * @return mixed The original value used to construct the decorator
+   */
+  public function getRawValue()
+  {
+    return $this->value;
+  }
+  
+  /**
+   * Gets a value from the escaper.
+   *
+   * @param string Value to get
+   *
+   * @return mixed Value
+   */
+  public function __get($var)
+  {
+    return $this->escape($this->escapingMethod, $this->value->$var);
+  }
+}

lib/symfony/view/escaper/sfOutputEscaperArrayDecorator.class.php

@@ -0,0 +1,173 @@
+<?php
+
+/*
+ * This file is part of the symfony package.
+ * (c) 2004-2006 Fabien Potencier <fabien.potencier@symfony-project.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+// fix for PHP 5.0 (no Countable interface)
+if (!interface_exists('Countable', false))
+{
+  interface Countable
+  {
+    public function count();
+  }
+}
+
+/**
+ * Output escaping decorator class for arrays.
+ *
+ * @see        sfOutputEscaper
+ * @package    symfony
+ * @subpackage view
+ * @author     Mike Squire <mike@somosis.co.uk>
+ * @version    SVN: $Id: sfOutputEscaperArrayDecorator.class.php 3232 2007-01-11 20:51:54Z fabien $
+ */
+class sfOutputEscaperArrayDecorator extends sfOutputEscaperGetterDecorator implements Iterator, ArrayAccess, Countable
+{
+  /**
+   * Used by the iterator to know if the current element is valid.
+   *
+   * @var int
+   */
+  private $count;
+
+  /**
+   * Reset the array to the beginning (as required for the Iterator interface).
+   */
+  public function rewind()
+  {
+    reset($this->value);
+
+    $this->count = count($this->value);
+  }
+
+  /**
+   * Get the key associated with the current value (as required by the Iterator interface).
+   *
+   * @return string The key
+   */
+  public function key()
+  {
+    return key($this->value);
+  }
+
+  /**
+   * Escapes and return the current value (as required by the Iterator interface).
+   *
+   * This escapes the value using {@link sfOutputEscaper::escape()} with
+   * whatever escaping method is set for this instance.
+   *
+   * @return mixed The escaped value
+   */
+  public function current()
+  {
+    return sfOutputEscaper::escape($this->escapingMethod, current($this->value));
+  }
+
+  /**
+   * Moves to the next element (as required by the Iterator interface).
+   */
+  public function next()
+  {
+    next($this->value);
+
+    $this->count --;
+  }
+
+  /**
+   * Returns true if the current element is valid (as required by the Iterator interface).
+   *
+   * The current element will not be valid if {@link next()} has fallen off the
+   * end of the array or if there are no elements in the array and {@link
+   * rewind()} was called.
+   *
+   * @return boolean The validity of the current element; true if it is valid
+   */
+  public function valid()
+  {
+    return $this->count > 0;
+  }
+
+  /**
+   * Returns true if the supplied offset is set in the array (as required by the ArrayAccess interface).
+   *
+   * @param string The offset of the value to check existance of
+   *
+   * @return boolean true if the offset exists; false otherwise
+   */
+  public function offsetExists($offset)
+  {
+    return array_key_exists($offset, $this->value);
+  }
+
+  /**
+   * Returns the element associated with the offset supplied (as required by the ArrayAccess interface).
+   *
+   * @param string The offset of the value to get
+   *
+   * @return mixed The escaped value
+   */
+  public function offsetGet($offset)
+  {
+    return sfOutputEscaper::escape($this->escapingMethod, $this->value[$offset]);
+  }
+
+  /**
+   * Throws an exception saying that values cannot be set (this method is
+   * required for the ArrayAccess interface).
+   *
+   * This (and the other sfOutputEscaper classes) are designed to be read only
+   * so this is an illegal operation.
+   *
+   * @param string (ignored)
+   * @param string (ignored)
+   *
+   * @throws <b>sfException</b>
+   */
+  public function offsetSet($offset, $value)
+  {
+    throw new sfException('Cannot set values.');
+  }
+
+  /**
+   * Throws an exception saying that values cannot be unset (this method is
+   * required for the ArrayAccess interface).
+   *
+   * This (and the other sfOutputEscaper classes) are designed to be read only
+   * so this is an illegal operation.
+   *
+   * @param string (ignored)
+   *
+   * @throws sfException
+   */
+  public function offsetUnset($offset)
+  {
+    throw new sfException('Cannot unset values.');
+  }
+
+  /**
+   * Returns the size of the array (are required by the Countable interface).
+   *
+   * @return int The size of the array
+   */
+  public function count()
+  {
+    return count($this->value);
+  }
+
+  /**
+   * Returns the (unescaped) value from the array associated with the key supplied.
+   *
+   * @param string The key into the array to use
+   *
+   * @return mixed The value
+   */
+  public function getRaw($key)
+  {
+    return $this->value[$key];
+  }
+}

lib/symfony/view/escaper/sfOutputEscaperGetterDecorator.class.php

@@ -0,0 +1,54 @@
+<?php
+
+/*
+ * This file is part of the symfony package.
+ * (c) 2004-2006 Fabien Potencier <fabien.potencier@symfony-project.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/**
+ * Abstract output escaping decorator class for "getter" objects.
+ *
+ * @see        sfOutputEscaper
+ * @package    symfony
+ * @subpackage view
+ * @author     Mike Squire <mike@somosis.co.uk>
+ * @version    SVN: $Id: sfOutputEscaperGetterDecorator.class.php 3232 2007-01-11 20:51:54Z fabien $
+ */
+abstract class sfOutputEscaperGetterDecorator extends sfOutputEscaper
+{
+  /**
+   * Returns the raw, unescaped value associated with the key supplied.
+   *
+   * The key might be an index into an array or a value to be passed to the 
+   * decorated object's get() method.
+   *
+   * @param string The key to retrieve
+   *
+   * @return mixed The value
+   */
+  public abstract function getRaw($key);
+
+  /**
+   * Returns the escaped value associated with the key supplied.
+   *
+   * Typically (using this implementation) the raw value is obtained using the
+   * {@link getRaw()} method, escaped and the result returned.
+   *
+   * @param string The key to retieve
+   * @param string The escaping method (a PHP function) to use
+   *
+   * @return mixed The escaped value
+   */
+  public function get($key, $escapingMethod = null)
+  {
+    if (!$escapingMethod)
+    {
+      $escapingMethod = $this->escapingMethod;
+    }
+
+    return sfOutputEscaper::escape($escapingMethod, $this->getRaw($key));
+  }
+}

lib/symfony/view/escaper/sfOutputEscaperIteratorDecorator.class.php

@@ -0,0 +1,170 @@
+<?php
+
+/*
+ * This file is part of the symfony package.
+ * (c) 2004-2006 Fabien Potencier <fabien.potencier@symfony-project.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/**
+ * Output escaping iterator decorator.
+ *
+ * This takes an object that implements the Traversable interface and turns it
+ * into an iterator with each value escaped.
+ *
+ * Note: Prior to PHP 5.1, the IteratorIterator class was not implemented in the
+ * core of PHP. This means that although it will still work with classes that
+ * implement Iterator or IteratorAggregate, internal PHP classes that only
+ * implement the Traversable interface will cause the constructor to throw an
+ * exception.
+ *
+ * @see        sfOutputEscaper
+ * @package    symfony
+ * @subpackage view
+ * @author     Mike Squire <mike@somosis.co.uk>
+ * @version    SVN: $Id: sfOutputEscaperIteratorDecorator.class.php 3232 2007-01-11 20:51:54Z fabien $
+ */
+class sfOutputEscaperIteratorDecorator extends sfOutputEscaperObjectDecorator implements Iterator, Countable, ArrayAccess
+{
+  /**
+   * The iterator to be used.
+   *
+   * @var IteratorIterator
+   */
+  private $iterator;
+
+  /**
+   * Constructs a new escaping iteratoror using the escaping method and value supplied.
+   *
+   * @param string The escaping method to use
+   * @param Traversable The iterator to escape
+   */
+  public function __construct($escapingMethod, Traversable $value)
+  {
+    // Set the original value for __call(). Set our own iterator because passing
+    // it to IteratorIterator will lose any other method calls.
+
+    parent::__construct($escapingMethod, $value);
+
+    $this->iterator = new IteratorIterator($value);
+  }
+
+  /**
+   * Resets the iterator (as required by the Iterator interface).
+   *
+   * @return boolean true, if the iterator rewinds successfully otherwise false
+   */
+  public function rewind()
+  {
+    return $this->iterator->rewind();
+  }
+
+  /**
+   * Escapes and gets the current element (as required by the Iterator interface).
+   *
+   * @return mixed The escaped value
+   */
+  public function current()
+  {
+    return sfOutputEscaper::escape($this->escapingMethod, $this->iterator->current());
+  }
+
+  /**
+   * Gets the current key (as required by the Iterator interface).
+   *
+   * @return string Iterator key
+   */
+  public function key()
+  {
+    return $this->iterator->key();
+  }
+
+  /**
+   * Moves to the next element in the iterator (as required by the Iterator interface).
+   */
+  public function next()
+  {
+    return $this->iterator->next();
+  }
+
+  /**
+   * Returns whether the current element is valid or not (as required by the
+   * Iterator interface).
+   *
+   * @return boolean true if the current element is valid; false otherwise
+   */
+  public function valid()
+  {
+    return $this->iterator->valid();
+  }
+  
+  /**
+   * Returns true if the supplied offset is set in the array (as required by
+   * the ArrayAccess interface).
+   *
+   * @param string The offset of the value to check existance of
+   *
+   * @return boolean true if the offset exists; false otherwise
+   */
+  public function offsetExists($offset)
+  {
+    return array_key_exists($offset, $this->value);
+  }
+
+  /**
+   * Returns the element associated with the offset supplied (as required by the ArrayAccess interface).
+   *
+   * @param string The offset of the value to get
+   *
+   * @return mixed The escaped value
+   */
+  public function offsetGet($offset)
+  {
+    return sfOutputEscaper::escape($this->escapingMethod, $this->value[$offset]);
+  }
+
+  /**
+   * Throws an exception saying that values cannot be set (this method is
+   * required for the ArrayAccess interface).
+   *
+   * This (and the other sfOutputEscaper classes) are designed to be read only
+   * so this is an illegal operation.
+   *
+   * @param string (ignored)
+   * @param string (ignored)
+   *
+   * @throws <b>sfException</b>
+   */
+  public function offsetSet($offset, $value)
+  {
+    throw new sfException('Cannot set values.');
+  }
+
+  /**
+   * Throws an exception saying that values cannot be unset (this method is
+   * required for the ArrayAccess interface).
+   *
+   * This (and the other sfOutputEscaper classes) are designed to be read only
+   * so this is an illegal operation.
+   *
+   * @param string (ignored)
+   *
+   * @throws <b>sfException</b>
+   */
+  public function offsetUnset($offset)
+  {
+    throw new sfException('Cannot unset values.');
+  }
+
+  /**
+   * Returns the size of the array (are required by the Countable interface).
+   *
+   * @return int The size of the array
+   */
+  public function count()
+  {
+    return count($this->value);
+  }
+}

lib/symfony/view/escaper/sfOutputEscaperObjectDecorator.class.php

@@ -0,0 +1,109 @@
+<?php
+
+/*
+ * This file is part of the symfony package.
+ * (c) 2004-2006 Fabien Potencier <fabien.potencier@symfony-project.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/**
+ * Output escaping object decorator that intercepts all method calls and escapes
+ * their return values.
+ *
+ * @see        sfOutputEscaper
+ * @package    symfony
+ * @subpackage view
+ * @author     Mike Squire <mike@somosis.co.uk>
+ * @version    SVN: $Id: sfOutputEscaperObjectDecorator.class.php 3232 2007-01-11 20:51:54Z fabien $
+ */
+class sfOutputEscaperObjectDecorator extends sfOutputEscaperGetterDecorator
+{
+  /**
+   * Magic PHP method that intercepts method calls, calls them on the objects
+   * that is being escaped and escapes the result.
+   *
+   * The calling of the method is changed slightly to accommodate passing a
+   * specific escaping strategy. An additional parameter is appended to the
+   * argument list which is the escaping strategy. The decorator will remove
+   * and use this parameter as the escaping strategy if it begins with 'esc_'
+   * (the prefix all escaping helper functions have).
+   *
+   * For example if an object, $o, implements methods a() and b($arg):
+   *
+   *   $o->a()                // Escapes the return value of a()
+   *   $o->a(ESC_RAW)         // Uses the escaping method ESC_RAW with a()
+   *   $o->b('a')             // Escapes the return value of b('a')
+   *   $o->b('a', ESC_RAW);   // Uses the escaping method ESC_RAW with b('a')
+   *
+   * @param string The method on the object to be called
+   * @param array An array of arguments to be passed to the method
+   *
+   * @return mixed The escaped value returned by the method
+   */
+  public function __call($method, $args)
+  {
+    if (count($args) > 0)
+    {
+      $escapingMethod = $args[count($args) - 1];
+      if (is_string($escapingMethod) && substr($escapingMethod, 0, 4) === 'esc_')
+      {
+        array_pop($args);
+      }
+      else
+      {
+        $escapingMethod = $this->escapingMethod;
+      }
+    }
+    else
+    {
+      $escapingMethod = $this->escapingMethod;
+    }
+
+    $value = call_user_func_array(array($this->value, $method), $args);
+
+    return sfOutputEscaper::escape($escapingMethod, $value);
+  }
+
+  /**
+   * Returns the result of calling the get() method on the object, bypassing
+   * any escaping, if that method exists.
+   *
+   * If there is not a callable get() method this will throw an exception.
+   *
+   * @param string The parameter to be passed to the get() get method
+   *
+   * @return mixed The unescaped value returned
+   *
+   * @throws <b>sfException</b> if the object does not have a callable get() method
+   */
+  public function getRaw($key)
+  {
+    if (!is_callable(array($this->value, 'get')))
+    {
+      throw new sfException('Object does not have a callable get() method.');
+    }
+
+    return $this->value->get($key);
+  }
+
+  /**
+   * Try to call decorated object __toString() method if exists.
+   *
+   * @return string
+   *
+   * @throws <b>sfException</b>
+   */
+  public function __toString()
+  {
+    if (method_exists($this->value, '__toString'))
+    {
+      return $this->value->__toString();
+    }
+    else
+    {
+      throw new sfException(sprintf('Object of class "%s" cannot be converted to string (Please create a __toString() method)', get_class($this->value)));
+    }
+  }
+}