[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   * (c) 2004-2006 Sean Kerr.
   7   *
   8   * For the full copyright and license information, please view the LICENSE
   9   * file that was distributed with this source code.
  10   */
  11  
  12  /**
  13   * sfRequest provides methods for manipulating client request information such
  14   * as attributes, errors and parameters. It is also possible to manipulate the
  15   * request method originally sent by the user.
  16   *
  17   * @package    symfony
  18   * @subpackage request
  19   * @author     Fabien Potencier <fabien.potencier@symfony-project.com>
  20   * @author     Sean Kerr <skerr@mojavi.org>
  21   * @version    SVN: $Id: sfRequest.class.php 3329 2007-01-23 08:29:34Z fabien $
  22   */
  23  abstract class sfRequest
  24  {
  25    /**
  26     * Process validation and execution for only GET requests.
  27     *
  28     */
  29    const GET = 2;
  30  
  31    /**
  32     * Skip validation and execution for any request method.
  33     *
  34     */
  35    const NONE = 1;
  36  
  37    /**
  38     * Process validation and execution for only POST requests.
  39     *
  40     */
  41    const POST = 4;
  42  
  43    /**
  44     * Process validation and execution for only PUT requests.
  45     *
  46     */
  47    const PUT = 5;
  48  
  49    /**
  50     * Process validation and execution for only DELETE requests.
  51     *
  52     */
  53    const DELETE = 6;
  54  
  55    /**
  56     * Process validation and execution for only HEAD requests.
  57     *
  58     */
  59    const HEAD = 7;
  60  
  61    protected
  62      $errors          = array(),
  63      $context         = null,
  64      $method          = null,
  65      $parameterHolder = null,
  66      $config          = null,
  67      $attributeHolder = null;
  68  
  69    /**
  70     * Extracts parameter values from the request.
  71     *
  72     * @param array An indexed array of parameter names to extract
  73     *
  74     * @return array An associative array of parameters and their values. If
  75     *               a specified parameter doesn't exist an empty string will
  76     *               be returned for its value
  77     */
  78    public function & extractParameters($names)
  79    {
  80      $array = array();
  81  
  82      $parameters =& $this->parameterHolder->getAll();
  83      foreach ($parameters as $key => &$value)
  84      {
  85        if (in_array($key, $names))
  86        {
  87          $array[$key] =& $value;
  88        }
  89      }
  90  
  91      return $array;
  92    }
  93  
  94    /**
  95     * Retrieves an error message.
  96     *
  97     * @param string An error name
  98     *
  99     * @return string An error message, if the error exists, otherwise null
 100     */
 101    public function getError($name, $catalogue = 'messages')
 102    {
 103      $retval = null;
 104  
 105      if (isset($this->errors[$name]))
 106      {
 107        $retval = $this->errors[$name];
 108      }
 109  
 110      // translate error message if needed
 111      if (sfConfig::get('sf_i18n'))
 112      {
 113        $retval = $this->context->getI18N()->__($retval, null, $catalogue);
 114      }
 115  
 116      return $retval;
 117    }
 118  
 119    /**
 120     * Retrieves an array of error names.
 121     *
 122     * @return array An indexed array of error names
 123     */
 124    public function getErrorNames()
 125    {
 126      return array_keys($this->errors);
 127    }
 128  
 129    /**
 130     * Retrieves an array of errors.
 131     *
 132     * @return array An associative array of errors
 133     */
 134    public function getErrors()
 135    {
 136      return $this->errors;
 137    }
 138  
 139    /**
 140     * Retrieves this request's method.
 141     *
 142     * @return int One of the following constants:
 143     *             - sfRequest::GET
 144     *             - sfRequest::POST
 145     */
 146    public function getMethod()
 147    {
 148      return $this->method;
 149    }
 150  
 151    /**
 152     * Indicates whether or not an error exists.
 153     *
 154     * @param string An error name
 155     *
 156     * @return boolean true, if the error exists, otherwise false
 157     */
 158    public function hasError($name)
 159    {
 160      return isset($this->errors[$name]);
 161    }
 162  
 163    /**
 164     * Indicates whether or not any errors exist.
 165     *
 166     * @return boolean true, if any error exist, otherwise false
 167     */
 168    public function hasErrors()
 169    {
 170      return (count($this->errors) > 0);
 171    }
 172  
 173    /**
 174     * Initializes this sfRequest.
 175     *
 176     * @param sfContext A sfContext instance
 177     * @param array   An associative array of initialization parameters
 178     * @param array   An associative array of initialization attributes
 179     *
 180     * @return boolean true, if initialization completes successfully, otherwise false
 181     *
 182     * @throws <b>sfInitializationException</b> If an error occurs while initializing this Request
 183     */
 184    public function initialize($context, $parameters = array(), $attributes = array())
 185    {
 186      $this->context = $context;
 187  
 188      // initialize parameter and attribute holders
 189      $this->parameterHolder = new sfParameterHolder();
 190      $this->attributeHolder = new sfParameterHolder();
 191  
 192      $this->parameterHolder->add($parameters);
 193      $this->attributeHolder->add($attributes);
 194    }
 195  
 196    /**
 197     * Retrieves the current application context.
 198     *
 199     * @return sfContext Current application context
 200     */
 201    public function getContext()
 202    {
 203      return $this->context;
 204    }
 205  
 206    /**
 207     * Retrieves a new sfRequest implementation instance.
 208     *
 209     * @param string A sfRequest implementation name
 210     *
 211     * @return sfRequest A sfRequest implementation instance
 212     *
 213     * @throws <b>sfFactoryException</b> If a request implementation instance cannot be created
 214     */
 215    public static function newInstance($class)
 216    {
 217      // the class exists
 218      $object = new $class();
 219  
 220      if (!($object instanceof sfRequest))
 221      {
 222        // the class name is of the wrong type
 223        $error = 'Class "%s" is not of the type sfRequest';
 224        $error = sprintf($error, $class);
 225  
 226        throw new sfFactoryException($error);
 227      }
 228  
 229      return $object;
 230    }
 231  
 232    /**
 233     * Removes an error.
 234     *
 235     * @param string An error name
 236     *
 237     * @return string An error message, if the error was removed, otherwise null
 238     */
 239    public function & removeError($name)
 240    {
 241      $retval = null;
 242  
 243      if (isset($this->errors[$name]))
 244      {
 245        $retval =& $this->errors[$name];
 246  
 247        unset($this->errors[$name]);
 248      }
 249  
 250      return $retval;
 251    }
 252  
 253    /**
 254     * Sets an error.
 255     *
 256     * @param string An error name
 257     * @param string An error message
 258     *
 259     */
 260    public function setError($name, $message)
 261    {
 262      if (sfConfig::get('sf_logging_enabled'))
 263      {
 264        $this->getContext()->getLogger()->info('{sfRequest} error in form for parameter "'.$name.'" (with message "'.$message.'")');
 265      }
 266  
 267      $this->errors[$name] = $message;
 268    }
 269  
 270    /**
 271     * Sets an array of errors
 272     *
 273     * If an existing error name matches any of the keys in the supplied
 274     * array, the associated message will be overridden.
 275     *
 276     * @param array An associative array of errors and their associated messages
 277     *
 278     */
 279    public function setErrors($errors)
 280    {
 281      $this->errors = array_merge($this->errors, $errors);
 282    }
 283  
 284    /**
 285     * Sets the request method.
 286     *
 287     * @param int One of the following constants:
 288     *
 289     * - sfRequest::GET
 290     * - sfRequest::POST
 291     * - sfRequest::PUT
 292     * - sfRequest::DELETE
 293     * - sfRequest::HEAD
 294     *
 295     * @return void
 296     *
 297     * @throws <b>sfException</b> - If the specified request method is invalid
 298     */
 299    public function setMethod($methodCode)
 300    {
 301      $available_methods = array(self::GET, self::POST, self::PUT, self::DELETE, self::HEAD, self::NONE);
 302      if (in_array($methodCode, $available_methods))
 303      {
 304        $this->method = $methodCode;
 305  
 306        return;
 307      }
 308  
 309      // invalid method type
 310      $error = 'Invalid request method: %s';
 311      $error = sprintf($error, $methodCode);
 312  
 313      throw new sfException($error);
 314    }
 315  
 316    /**
 317     * Retrieves the parameters for the current request.
 318     *
 319     * @return sfParameterHolder The parameter holder
 320     */
 321    public function getParameterHolder()
 322    {
 323      return $this->parameterHolder;
 324    }
 325  
 326    /**
 327     * Retrieves the attributes holder.
 328     *
 329     * @return sfParameterHolder The attribute holder
 330     */
 331    public function getAttributeHolder()
 332    {
 333      return $this->attributeHolder;
 334    }
 335  
 336    /**
 337     * Retrieves an attribute from the current request.
 338     *
 339     * @param string Attribute name
 340     * @param string Default attribute value
 341     * @param string Namespace for the current request
 342     *
 343     * @return mixed An attribute value
 344     */
 345    public function getAttribute($name, $default = null, $ns = null)
 346    {
 347      return $this->attributeHolder->get($name, $default, $ns);
 348    }
 349  
 350    /**
 351     * Indicates whether or not an attribute exist for the current request.
 352     *
 353     * @param string Attribute name
 354     * @param string Namespace for the current request
 355     *
 356     * @return boolean true, if the attribute exists otherwise false
 357     */
 358    public function hasAttribute($name, $ns = null)
 359    {
 360      return $this->attributeHolder->has($name, $ns);
 361    }
 362  
 363    /**
 364     * Sets an attribute for the request.
 365     *
 366     * @param string Attribute name
 367     * @param string Value for the attribute
 368     * @param string Namespace for the current request
 369     *
 370     */
 371    public function setAttribute($name, $value, $ns = null)
 372    {
 373      $this->attributeHolder->set($name, $value, $ns);
 374    }
 375  
 376    /**
 377     * Retrieves a paramater for the current request.
 378     *
 379     * @param string Parameter name
 380     * @param string Parameter default value
 381     * @param string Namespace for the current request
 382     *
 383     */
 384    public function getParameter($name, $default = null, $ns = null)
 385    {
 386      return $this->parameterHolder->get($name, $default, $ns);
 387    }
 388  
 389    /**
 390     * Indicates whether or not a parameter exist for the current request.
 391     *
 392     * @param string Parameter name
 393     * @param string Namespace for the current request
 394     *
 395     * @return boolean true, if the paramater exists otherwise false
 396     */
 397    public function hasParameter($name, $ns = null)
 398    {
 399      return $this->parameterHolder->has($name, $ns);
 400    }
 401  
 402    /**
 403     * Sets a parameter for the current request.
 404     *
 405     * @param string Parameter name
 406     * @param string Parameter value
 407     * @param string Namespace for the current request
 408     *
 409     */
 410    public function setParameter($name, $value, $ns = null)
 411    {
 412      $this->parameterHolder->set($name, $value, $ns);
 413    }
 414  
 415    /**
 416     * Executes the shutdown procedure.
 417     *
 418     */
 419    abstract function shutdown();
 420  
 421    /**
 422     * Overloads a given method.
 423     *
 424     * @param string Method name
 425     * @param string Method arguments
 426     *
 427     * @return mixed User function callback
 428     *
 429     * @throws <b>sfException</b> if call fails
 430     */
 431    public function __call($method, $arguments)
 432    {
 433      if (!$callable = sfMixer::getCallable('sfRequest:'.$method))
 434      {
 435        throw new sfException(sprintf('Call to undefined method sfRequest::%s', $method));
 436      }
 437  
 438      array_unshift($arguments, $this);
 439  
 440      return call_user_func_array($callable, $arguments);
 441    }
 442  }