Development

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

You must first sign up to be able to contribute.

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

Revision 20048, 15.6 kB (checked in by FabianLange, 5 years ago)

[1.2, 1.3] added phpdoc for compat exceptions (closes #6781)

  • Property svn:mime-type set to text/x-php
  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Rev Date
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     $this->getController()->redirect($url, 0, $statusCode);
196
197     throw new sfStopException();
198   }
199
200   /**
201    * Redirects current request to a new URL, only if specified condition is true.
202    *
203    * This method stops the action. So, no code is executed after a call to this method.
204    *
205    * @param bool   $condition  A condition that evaluates to true or false
206    * @param string $url        Url
207    * @param string $statusCode Status code (default to 302)
208    *
209    * @throws sfStopException
210    *
211    * @see redirect
212    */
213   public function redirectIf($condition, $url, $statusCode = 302)
214   {
215     if ($condition)
216     {
217       $this->redirect($url, $statusCode);
218     }
219   }
220
221   /**
222    * Redirects current request to a new URL, unless specified condition is true.
223    *
224    * This method stops the action. So, no code is executed after a call to this method.
225    *
226    * @param bool   $condition  A condition that evaluates to true or false
227    * @param string $url        Url
228    * @param string $statusCode Status code (default to 302)
229    *
230    * @throws sfStopException
231    *
232    * @see redirect
233    */
234   public function redirectUnless($condition, $url, $statusCode = 302)
235   {
236     if (!$condition)
237     {
238       $this->redirect($url, $statusCode);
239     }
240   }
241
242   /**
243    * Appends the given text to the response content and bypasses the built-in view system.
244    *
245    * This method must be called as with a return:
246    *
247    * <code>return $this->renderText('some text')</code>
248    *
249    * @param string $text Text to append to the response
250    *
251    * @return sfView::NONE
252    */
253   public function renderText($text)
254   {
255     $this->getResponse()->setContent($this->getResponse()->getContent().$text);
256
257     return sfView::NONE;
258   }
259
260   /**
261    * Returns the partial rendered content.
262    *
263    * If the vars parameter is omitted, the action's internal variables
264    * will be passed, just as it would to a normal template.
265    *
266    * If the vars parameter is set then only those values are
267    * available in the partial.
268    *
269    * @param string $templateName partial name
270    * @param array  $vars         vars
271    *
272    * @return string The partial content
273    */
274   public function getPartial($templateName, $vars = null)
275   {
276     $this->getContext()->getConfiguration()->loadHelpers('Partial');
277
278     $vars = !is_null($vars) ? $vars : $this->varHolder->getAll();
279
280     return get_partial($templateName, $vars);
281   }
282
283   /**
284    * Appends the result of the given partial execution to the response content.
285    *
286    * This method must be called as with a return:
287    *
288    * <code>return $this->renderPartial('foo/bar')</code>
289    *
290    * @param string $templateName partial name
291    * @param array  $vars         vars
292    *
293    * @return sfView::NONE
294    *
295    * @see    getPartial
296    */
297   public function renderPartial($templateName, $vars = null)
298   {
299     return $this->renderText($this->getPartial($templateName, $vars));
300   }
301
302   /**
303    * Returns the component rendered content.
304    *
305    * If the vars parameter is omitted, the action's internal variables
306    * will be passed, just as it would to a normal template.
307    *
308    * If the vars parameter is set then only those values are
309    * available in the component.
310    *
311    * @param string $moduleName    module name
312    * @param string $componentName component name
313    * @param array  $vars          vars
314    *
315    * @return string  The component rendered content
316    */
317   public function getComponent($moduleName, $componentName, $vars = null)
318   {
319     $this->getContext()->getConfiguration()->loadHelpers('Partial');
320
321     $vars = !is_null($vars) ? $vars : $this->varHolder->getAll();
322
323     return get_component($moduleName, $componentName, $vars);
324   }
325
326   /**
327    * Appends the result of the given component execution to the response content.
328    *
329    * This method must be called as with a return:
330    *
331    * <code>return $this->renderComponent('foo', 'bar')</code>
332    *
333    * @param string $moduleName    module name
334    * @param string $componentName component name
335    * @param array  $vars          vars
336    *
337    * @return sfView::NONE
338    *
339    * @see    getComponent
340    */
341   public function renderComponent($moduleName, $componentName, $vars = null)
342   {
343     return $this->renderText($this->getComponent($moduleName, $componentName, $vars));
344   }
345
346   /**
347    * Retrieves the default view to be executed when a given request is not served by this action.
348    *
349    * @return string A string containing the view name associated with this action
350    *
351    * @throws sfConfigurationException If compat_10 is not enabled
352    */
353   public function getDefaultView()
354   {
355     if (!sfConfig::get('sf_compat_10'))
356     {
357       throw new sfConfigurationException('You must set "compat_10" to true if you want to use this method which is deprecated.');
358     }
359
360     return sfView::INPUT;
361   }
362
363   /**
364    * Executes any post-validation error application logic.
365    *
366    * @return string A string containing the view name associated with this action
367    *
368    * @throws sfConfigurationException If compat_10 is not enabled
369    */
370   public function handleError()
371   {
372     if (!sfConfig::get('sf_compat_10'))
373     {
374       throw new sfConfigurationException('You must set "compat_10" to true if you want to use this method which is deprecated.');
375     }
376
377     return sfView::ERROR;
378   }
379
380   /**
381    * Validates manually files and parameters.
382    *
383    * @return bool true, if validation completes successfully, otherwise false.
384    *
385    * @throws sfConfigurationException If compat_10 is not enabled
386    */
387   public function validate()
388   {
389     if (!sfConfig::get('sf_compat_10'))
390     {
391       throw new sfConfigurationException('You must set "compat_10" to true if you want to use this method which is deprecated.');
392     }
393
394     return true;
395   }
396
397   /**
398    * Returns the security configuration for this module.
399    *
400    * @return string Current security configuration as an array
401    */
402   public function getSecurityConfiguration()
403   {
404     return $this->security;
405   }
406
407   /**
408    * Overrides the current security configuration for this module.
409    *
410    * @param array $security The new security configuration
411    */
412   public function setSecurityConfiguration($security)
413   {
414     $this->security = $security;
415   }
416
417   /**
418    * Indicates that this action requires security.
419    *
420    * @return bool true, if this action requires security, otherwise false.
421    */
422   public function isSecure()
423   {
424     $actionName = strtolower($this->getActionName());
425
426     if (isset($this->security[$actionName]['is_secure']))
427     {
428       return $this->security[$actionName]['is_secure'];
429     }
430
431     if (isset($this->security['all']['is_secure']))
432     {
433       return $this->security['all']['is_secure'];
434     }
435
436     return false;
437   }
438
439   /**
440    * Gets credentials the user must have to access this action.
441    *
442    * @return mixed An array or a string describing the credentials the user must have to access this action
443    */
444   public function getCredential()
445   {
446     $actionName = strtolower($this->getActionName());
447
448     if (isset($this->security[$actionName]['credentials']))
449     {
450       $credentials = $this->security[$actionName]['credentials'];
451     }
452     else if (isset($this->security['all']['credentials']))
453     {
454       $credentials = $this->security['all']['credentials'];
455     }
456     else
457     {
458       $credentials = null;
459     }
460
461     return $credentials;
462   }
463
464   /**
465    * Sets an alternate template for this sfAction.
466    *
467    * See 'Naming Conventions' in the 'Symfony View' documentation.
468    *
469    * @param string $name   Template name
470    * @param string $module The module (current if null)
471    */
472   public function setTemplate($name, $module = null)
473   {
474     if (sfConfig::get('sf_logging_enabled'))
475     {
476       $this->dispatcher->notify(new sfEvent($this, 'application.log', array(sprintf('Change template to "%s/%s"', is_null($module) ? 'CURRENT' : $module, $name))));
477     }
478
479     if (!is_null($module))
480     {
481       $name = sfConfig::get('sf_app_dir').'/modules/'.$module.'/templates/'.$name;
482     }
483
484     sfConfig::set('symfony.view.'.$this->getModuleName().'_'.$this->getActionName().'_template', $name);
485   }
486
487   /**
488    * Gets the name of the alternate template for this sfAction.
489    *
490    * WARNING: It only returns the template you set with the setTemplate() method,
491    *          and does not return the template that you configured in your view.yml.
492    *
493    * See 'Naming Conventions' in the 'Symfony View' documentation.
494    *
495    * @return string Template name. Returns null if no template has been set within the action
496    */
497   public function getTemplate()
498   {
499     return sfConfig::get('symfony.view.'.$this->getModuleName().'_'.$this->getActionName().'_template');
500   }
501
502   /**
503    * Sets an alternate layout for this sfAction.
504    *
505    * To de-activate the layout, set the layout name to false.
506    *
507    * To revert the layout to the one configured in the view.yml, set the template name to null.
508    *
509    * @param mixed $name Layout name or false to de-activate the layout
510    */
511   public function setLayout($name)
512   {
513     if (sfConfig::get('sf_logging_enabled'))
514     {
515       $this->dispatcher->notify(new sfEvent($this, 'application.log', array(sprintf('Change layout to "%s"', $name))));
516     }
517
518     sfConfig::set('symfony.view.'.$this->getModuleName().'_'.$this->getActionName().'_layout', $name);
519   }
520
521   /**
522    * Gets the name of the alternate layout for this sfAction.
523    *
524    * WARNING: It only returns the layout you set with the setLayout() method,
525    *          and does not return the layout that you configured in your view.yml.
526    *
527    * @return mixed Layout name. Returns null if no layout has been set within the action
528    */
529   public function getLayout()
530   {
531     return sfConfig::get('symfony.view.'.$this->getModuleName().'_'.$this->getActionName().'_layout');
532   }
533
534   /**
535    * Changes the default view class used for rendering the template associated with the current action.
536    *
537    * @param string $class View class name
538    */
539   public function setViewClass($class)
540   {
541     sfConfig::set('mod_'.strtolower($this->getModuleName()).'_view_class', $class);
542   }
543
544   public function getRoute()
545   {
546     return $this->getRequest()->getAttribute('sf_route');
547   }
548
549   /**
550    * Returns a formatted message for a 404 error.
551    *
552    * @param string $message An error message (null by default)
553    *
554    * @return string The error message or a default one if null
555    */
556   protected function get404Message($message = null)
557   {
558     return is_null($message) ? sprintf('This request has been forwarded to a 404 error page by the action "%s/%s".', $this->getModuleName(), $this->getActionName()) : $message;
559   }
560 }
561
Note: See TracBrowser for help on using the browser.