Development

/branches/1.3/lib/action/sfAction.class.php

You must first sign up to be able to contribute.

root/branches/1.3/lib/action/sfAction.class.php

Revision 24279, 16.3 kB (checked in by fabien, 5 years ago)

[1.3, 1.4] added missing PHPDoc (closes #7672)

  • Property svn:mime-type set to text/x-php
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
Line 
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 <sean@code-box.org>
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  * sfAction executes all the logic for the current request.
14  *
15  * @package    symfony
16  * @subpackage action
17  * @author     Fabien Potencier <fabien.potencier@symfony-project.com>
18  * @author     Sean Kerr <sean@code-box.org>
19  * @version    SVN: $Id$
20  */
21 abstract class sfAction extends sfComponent
22 {
23   protected
24     $security = array();
25
26   /**
27    * Initializes this action.
28    *
29    * @param sfContext $context    The current application context.
30    * @param string    $moduleName The module name.
31    * @param string    $actionName The action name.
32    *
33    * @return bool true, if initialization completes successfully, otherwise false
34    */
35   public function initialize($context, $moduleName, $actionName)
36   {
37     parent::initialize($context, $moduleName, $actionName);
38
39     // include security configuration
40     if ($file = $context->getConfigCache()->checkConfig('modules/'.$this->getModuleName().'/config/security.yml', true))
41     {
42       require($file);
43     }
44   }
45
46   /**
47    * Executes an application defined process prior to execution of this sfAction object.
48    *
49    * By default, this method is empty.
50    */
51   public function preExecute()
52   {
53   }
54
55   /**
56    * Execute an application defined process immediately after execution of this sfAction object.
57    *
58    * By default, this method is empty.
59    */
60   public function postExecute()
61   {
62   }
63
64   /**
65    * Forwards current action to the default 404 error action.
66    *
67    * @param string $message Message of the generated exception
68    *
69    * @throws sfError404Exception
70    *
71    */
72   public function forward404($message = null)
73   {
74     throw new sfError404Exception($this->get404Message($message));
75   }
76
77   /**
78    * Forwards current action to the default 404 error action unless the specified condition is true.
79    *
80    * @param bool    $condition  A condition that evaluates to true or false
81    * @param string  $message    Message of the generated exception
82    *
83    * @throws sfError404Exception
84    */
85   public function forward404Unless($condition, $message = null)
86   {
87     if (!$condition)
88     {
89       throw new sfError404Exception($this->get404Message($message));
90     }
91   }
92
93   /**
94    * Forwards current action to the default 404 error action if the specified condition is true.
95    *
96    * @param bool    $condition  A condition that evaluates to true or false
97    * @param string  $message    Message of the generated exception
98    *
99    * @throws sfError404Exception
100    */
101   public function forward404If($condition, $message = null)
102   {
103     if ($condition)
104     {
105       throw new sfError404Exception($this->get404Message($message));
106     }
107   }
108
109   /**
110    * Redirects current action to the default 404 error action (with browser redirection).
111    *
112    * This method stops the current code flow.
113    */
114   public function redirect404()
115   {
116     return $this->redirect('/'.sfConfig::get('sf_error_404_module').'/'.sfConfig::get('sf_error_404_action'));
117   }
118
119   /**
120    * Forwards current action to a new one (without browser redirection).
121    *
122    * This method stops the action. So, no code is executed after a call to this method.
123    *
124    * @param  string  $module  A module name
125    * @param  string  $action  An action name
126    *
127    * @throws sfStopException
128    */
129   public function forward($module, $action)
130   {
131     if (sfConfig::get('sf_logging_enabled'))
132     {
133       $this->dispatcher->notify(new sfEvent($this, 'application.log', array(sprintf('Forward to action "%s/%s"', $module, $action))));
134     }
135
136     $this->getController()->forward($module, $action);
137
138     throw new sfStopException();
139   }
140
141   /**
142    * If the condition is true, forwards current action to a new one (without browser redirection).
143    *
144    * This method stops the action. So, no code is executed after a call to this method.
145    *
146    * @param  bool   $condition  A condition that evaluates to true or false
147    * @param  string $module     A module name
148    * @param  string $action     An action name
149    *
150    * @throws sfStopException
151    */
152   public function forwardIf($condition, $module, $action)
153   {
154     if ($condition)
155     {
156       $this->forward($module, $action);
157     }
158   }
159
160   /**
161    * Unless the condition is true, forwards current action to a new one (without browser redirection).
162    *
163    * This method stops the action. So, no code is executed after a call to this method.
164    *
165    * @param  bool   $condition  A condition that evaluates to true or false
166    * @param  string $module     A module name
167    * @param  string $action     An action name
168    *
169    * @throws sfStopException
170    */
171   public function forwardUnless($condition, $module, $action)
172   {
173     if (!$condition)
174     {
175       $this->forward($module, $action);
176     }
177   }
178
179   /**
180    * Redirects current request to a new URL.
181    *
182    * 2 URL formats are accepted :
183    *  - a full URL: http://www.google.com/
184    *  - an internal URL (url_for() format): module/action
185    *
186    * This method stops the action. So, no code is executed after a call to this method.
187    *
188    * @param  string $url         Url
189    * @param  string $statusCode  Status code (default to 302)
190    *
191    * @throws sfStopException
192    */
193   public function redirect($url, $statusCode = 302)
194   {
195     // compatibility with url_for2() style signature
196     if (is_object($statusCode) || is_array($statusCode))
197     {
198       $url = array_merge(array('sf_route' => $url), is_object($statusCode) ? array('sf_subject' => $statusCode) : $statusCode);
199       $statusCode = func_num_args() >= 3 ? func_get_arg(2) : 302;
200     }
201
202     $this->getController()->redirect($url, 0, $statusCode);
203
204     throw new sfStopException();
205   }
206
207   /**
208    * Redirects current request to a new URL, only if specified condition is true.
209    *
210    * This method stops the action. So, no code is executed after a call to this method.
211    *
212    * @param  bool   $condition  A condition that evaluates to true or false
213    * @param  string $url        Url
214    * @param  string $statusCode Status code (default to 302)
215    *
216    * @throws sfStopException
217    *
218    * @see redirect
219    */
220   public function redirectIf($condition, $url, $statusCode = 302)
221   {
222     if ($condition)
223     {
224       // compatibility with url_for2() style signature
225       $arguments = func_get_args();
226       call_user_func_array(array($this, 'redirect'), array_slice($arguments, 1));
227     }
228   }
229
230   /**
231    * Redirects current request to a new URL, unless specified condition is true.
232    *
233    * This method stops the action. So, no code is executed after a call to this method.
234    *
235    * @param  bool   $condition  A condition that evaluates to true or false
236    * @param  string $url        Url
237    * @param  string $statusCode Status code (default to 302)
238    *
239    * @throws sfStopException
240    *
241    * @see redirect
242    */
243   public function redirectUnless($condition, $url, $statusCode = 302)
244   {
245     if (!$condition)
246     {
247       // compatibility with url_for2() style signature
248       $arguments = func_get_args();
249       call_user_func_array(array($this, 'redirect'), array_slice($arguments, 1));
250     }
251   }
252
253   /**
254    * Appends the given text to the response content and bypasses the built-in view system.
255    *
256    * This method must be called as with a return:
257    *
258    * <code>return $this->renderText('some text')</code>
259    *
260    * @param string $text Text to append to the response
261    *
262    * @return sfView::NONE
263    */
264   public function renderText($text)
265   {
266     $this->getResponse()->setContent($this->getResponse()->getContent().$text);
267
268     return sfView::NONE;
269   }
270
271   /**
272    * Returns the partial rendered content.
273    *
274    * If the vars parameter is omitted, the action's internal variables
275    * will be passed, just as it would to a normal template.
276    *
277    * If the vars parameter is set then only those values are
278    * available in the partial.
279    *
280    * @param  string $templateName partial name
281    * @param  array  $vars         vars
282    *
283    * @return string The partial content
284    */
285   public function getPartial($templateName, $vars = null)
286   {
287     $this->getContext()->getConfiguration()->loadHelpers('Partial');
288
289     $vars = null !== $vars ? $vars : $this->varHolder->getAll();
290
291     return get_partial($templateName, $vars);
292   }
293
294   /**
295    * Appends the result of the given partial execution to the response content.
296    *
297    * This method must be called as with a return:
298    *
299    * <code>return $this->renderPartial('foo/bar')</code>
300    *
301    * @param  string $templateName partial name
302    * @param  array  $vars         vars
303    *
304    * @return sfView::NONE
305    *
306    * @see    getPartial
307    */
308   public function renderPartial($templateName, $vars = null)
309   {
310     return $this->renderText($this->getPartial($templateName, $vars));
311   }
312
313   /**
314    * Returns the component rendered content.
315    *
316    * If the vars parameter is omitted, the action's internal variables
317    * will be passed, just as it would to a normal template.
318    *
319    * If the vars parameter is set then only those values are
320    * available in the component.
321    *
322    * @param  string  $moduleName    module name
323    * @param  string  $componentName  component name
324    * @param  array   $vars          vars
325    *
326    * @return string  The component rendered content
327    */
328   public function getComponent($moduleName, $componentName, $vars = null)
329   {
330     $this->getContext()->getConfiguration()->loadHelpers('Partial');
331
332     $vars = null !== $vars ? $vars : $this->varHolder->getAll();
333
334     return get_component($moduleName, $componentName, $vars);
335   }
336
337   /**
338    * Appends the result of the given component execution to the response content.
339    *
340    * This method must be called as with a return:
341    *
342    * <code>return $this->renderComponent('foo', 'bar')</code>
343    *
344    * @param  string  $moduleName    module name
345    * @param  string  $componentName  component name
346    * @param  array   $vars          vars
347    *
348    * @return sfView::NONE
349    *
350    * @see    getComponent
351    */
352   public function renderComponent($moduleName, $componentName, $vars = null)
353   {
354     return $this->renderText($this->getComponent($moduleName, $componentName, $vars));
355   }
356
357   /**
358    * Retrieves the default view to be executed when a given request is not served by this action.
359    *
360    * @return string A string containing the view name associated with this action
361    *
362    * @throws sfConfigurationException If compat_10 is not enabled
363    */
364   public function getDefaultView()
365   {
366     if (!sfConfig::get('sf_compat_10'))
367     {
368       throw new sfConfigurationException('You must set "compat_10" to true if you want to use this method which is deprecated.');
369     }
370
371     return sfView::INPUT;
372   }
373
374   /**
375    * Executes any post-validation error application logic.
376    *
377    * @return string A string containing the view name associated with this action
378    *
379    * @throws sfConfigurationException If compat_10 is not enabled
380    */
381   public function handleError()
382   {
383     if (!sfConfig::get('sf_compat_10'))
384     {
385       throw new sfConfigurationException('You must set "compat_10" to true if you want to use this method which is deprecated.');
386     }
387
388     return sfView::ERROR;
389   }
390
391   /**
392    * Validates manually files and parameters.
393    *
394    * @return bool true, if validation completes successfully, otherwise false.
395    *
396    * @throws sfConfigurationException If compat_10 is not enabled
397    */
398   public function validate()
399   {
400     if (!sfConfig::get('sf_compat_10'))
401     {
402       throw new sfConfigurationException('You must set "compat_10" to true if you want to use this method which is deprecated.');
403     }
404
405     return true;
406   }
407
408   /**
409    * Returns the security configuration for this module.
410    *
411    * @return string Current security configuration as an array
412    */
413   public function getSecurityConfiguration()
414   {
415     return $this->security;
416   }
417
418   /**
419    * Overrides the current security configuration for this module.
420    *
421    * @param array $security The new security configuration
422    */
423   public function setSecurityConfiguration($security)
424   {
425     $this->security = $security;
426   }
427
428   /**
429    * Returns a value from security.yml.
430    *
431    * @param string $name    The name of the value to pull from security.yml
432    * @param mixed  $default The default value to return if none is found in security.yml
433    *
434    * @return mixed
435    */
436   public function getSecurityValue($name, $default = null)
437   {
438     $actionName = strtolower($this->getActionName());
439
440     if (isset($this->security[$actionName][$name]))
441     {
442       return $this->security[$actionName][$name];
443     }
444
445     if (isset($this->security['all'][$name]))
446     {
447       return $this->security['all'][$name];
448     }
449
450     return $default;
451   }
452
453   /**
454    * Indicates that this action requires security.
455    *
456    * @return bool true, if this action requires security, otherwise false.
457    */
458   public function isSecure()
459   {
460     return $this->getSecurityValue('is_secure', false);
461   }
462
463   /**
464    * Gets credentials the user must have to access this action.
465    *
466    * @return mixed An array or a string describing the credentials the user must have to access this action
467    */
468   public function getCredential()
469   {
470     return $this->getSecurityValue('credentials');
471   }
472
473   /**
474    * Sets an alternate template for this sfAction.
475    *
476    * See 'Naming Conventions' in the 'Symfony View' documentation.
477    *
478    * @param string $name    Template name
479    * @param string $module  The module (current if null)
480    */
481   public function setTemplate($name, $module = null)
482   {
483     if (sfConfig::get('sf_logging_enabled'))
484     {
485       $this->dispatcher->notify(new sfEvent($this, 'application.log', array(sprintf('Change template to "%s/%s"', null === $module ? 'CURRENT' : $module, $name))));
486     }
487
488     if (null !== $module)
489     {
490       $name = sfConfig::get('sf_app_dir').'/modules/'.$module.'/templates/'.$name;
491     }
492
493     sfConfig::set('symfony.view.'.$this->getModuleName().'_'.$this->getActionName().'_template', $name);
494   }
495
496   /**
497    * Gets the name of the alternate template for this sfAction.
498    *
499    * WARNING: It only returns the template you set with the setTemplate() method,
500    *          and does not return the template that you configured in your view.yml.
501    *
502    * See 'Naming Conventions' in the 'Symfony View' documentation.
503    *
504    * @return string Template name. Returns null if no template has been set within the action
505    */
506   public function getTemplate()
507   {
508     return sfConfig::get('symfony.view.'.$this->getModuleName().'_'.$this->getActionName().'_template');
509   }
510
511   /**
512    * Sets an alternate layout for this sfAction.
513    *
514    * To de-activate the layout, set the layout name to false.
515    *
516    * To revert the layout to the one configured in the view.yml, set the template name to null.
517    *
518    * @param mixed $name Layout name or false to de-activate the layout
519    */
520   public function setLayout($name)
521   {
522     if (sfConfig::get('sf_logging_enabled'))
523     {
524       $this->dispatcher->notify(new sfEvent($this, 'application.log', array(sprintf('Change layout to "%s"', $name))));
525     }
526
527     sfConfig::set('symfony.view.'.$this->getModuleName().'_'.$this->getActionName().'_layout', $name);
528   }
529
530   /**
531    * Gets the name of the alternate layout for this sfAction.
532    *
533    * WARNING: It only returns the layout you set with the setLayout() method,
534    *          and does not return the layout that you configured in your view.yml.
535    *
536    * @return mixed Layout name. Returns null if no layout has been set within the action
537    */
538   public function getLayout()
539   {
540     return sfConfig::get('symfony.view.'.$this->getModuleName().'_'.$this->getActionName().'_layout');
541   }
542
543   /**
544    * Changes the default view class used for rendering the template associated with the current action.
545    *
546    * @param string $class View class name
547    */
548   public function setViewClass($class)
549   {
550     sfConfig::set('mod_'.strtolower($this->getModuleName()).'_view_class', $class);
551   }
552
553   /**
554    * Returns the current route for this request
555    *
556    * @return sfRoute The route for the request
557    */
558   public function getRoute()
559   {
560     return $this->getRequest()->getAttribute('sf_route');
561   }
562
563   /**
564    * Returns a formatted message for a 404 error.
565    *
566    * @param  string $message An error message (null by default)
567    *
568    * @return string The error message or a default one if null
569    */
570   protected function get404Message($message = null)
571   {
572     return null === $message ? sprintf('This request has been forwarded to a 404 error page by the action "%s/%s".', $this->getModuleName(), $this->getActionName()) : $message;
573   }
574 }
575
Note: See TracBrowser for help on using the browser.