documentation/manual/en/module_specs/Zend_View-Controllers.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.view.controllers">
   4     <title>Controller Scripts</title>
   5
   6     <para>
   7         The controller is where you instantiate and configure <classname>Zend_View</classname>.
   8         You then assign variables to the view, and tell the view to
   9         render output using a particular script.
  10     </para>
  11
  12     <sect2 id="zend.view.controllers.assign">
  13         <title>Assigning Variables</title>
  14
  15         <para>
  16             Your controller script should assign necessary variables to the view
  17             before it hands over control to the view script. Normally, you
  18             can do assignments one at a time by assigning to property names
  19             of the view instance:
  20         </para>
  21
  22         <programlisting language="php"><![CDATA[
  23 $view = new Zend_View();
  24 $view->a = "Hay";
  25 $view->b = "Bee";
  26 $view->c = "Sea";
  27 ]]></programlisting>
  28
  29         <para>
  30             However, this can be tedious when you have already collected the
  31             values to be assigned into an array or object.
  32         </para>
  33
  34         <para>
  35             The assign() method lets you assign from an array or object "in
  36             bulk". The following examples have the same effect as the above
  37             one-by-one property assignments.
  38         </para>
  39
  40         <programlisting language="php"><![CDATA[
  41 $view = new Zend_View();
  42
  43 // assign an array of key-value pairs, where the
  44 // key is the variable name, and the value is
  45 // the assigned value.
  46 $array = array(
  47     'a' => "Hay",
  48     'b' => "Bee",
  49     'c' => "Sea",
  50 );
  51 $view->assign($array);
  52
  53 // do the same with an object's public properties;
  54 // note how we cast it to an array when assigning.
  55 $obj = new StdClass;
  56 $obj->a = "Hay";
  57 $obj->b = "Bee";
  58 $obj->c = "Sea";
  59 $view->assign((array) $obj);
  60 ]]></programlisting>
  61
  62         <para>
  63             Alternatively, you can use the assign method to assign
  64             one-by-one by passing a string variable name, and then the
  65             variable value.
  66         </para>
  67
  68         <programlisting language="php"><![CDATA[
  69 $view = new Zend_View();
  70 $view->assign('a', "Hay");
  71 $view->assign('b', "Bee");
  72 $view->assign('c', "Sea");
  73 ]]></programlisting>
  74     </sect2>
  75
  76     <sect2 id="zend.view.controllers.render">
  77         <title>Rendering a View Script</title>
  78
  79         <para>
  80             Once you have assigned all needed variables, the controller
  81             should tell <classname>Zend_View</classname> to render a particular view script.
  82             Do so by calling the render() method. Note that the method will
  83             return the rendered view, not print it, so you need to print or
  84             echo it yourself at the appropriate time.
  85         </para>
  86
  87         <programlisting language="php"><![CDATA[
  88 $view = new Zend_View();
  89 $view->a = "Hay";
  90 $view->b = "Bee";
  91 $view->c = "Sea";
  92 echo $view->render('someView.php');
  93 ]]></programlisting>
  94     </sect2>
  95
  96     <sect2 id="zend.view.controllers.script-paths">
  97         <title>View Script Paths</title>
  98
  99         <para>
 100             By default, <classname>Zend_View</classname> expects your view scripts to be relative to
 101             your calling script. For example, if your controller script is at
 102             "/path/to/app/controllers" and it calls
 103             $view->render('someView.php'), <classname>Zend_View</classname> will look for
 104             "/path/to/app/controllers/someView.php".
 105         </para>
 106
 107         <para>
 108             Obviously, your view scripts are probably located elsewhere. To
 109             tell <classname>Zend_View</classname> where it should look for view scripts, use the
 110             setScriptPath() method.
 111         </para>
 112
 113         <programlisting language="php"><![CDATA[
 114 $view = new Zend_View();
 115 $view->setScriptPath('/path/to/app/views');
 116 ]]></programlisting>
 117
 118         <para>
 119             Now when you call $view->render('someView.php'), it will look
 120             for "/path/to/app/views/someView.php".
 121         </para>
 122
 123         <para>
 124             In fact, you can "stack" paths using the addScriptPath()
 125             method. As you add paths to the stack, <classname>Zend_View</classname> will look
 126             at the most-recently-added path for the requested view
 127             script. This allows you override default views with custom
 128             views so that you may create custom "themes" or "skins" for
 129             some views, while leaving others alone.
 130         </para>
 131
 132         <programlisting language="php"><![CDATA[
 133 $view = new Zend_View();
 134 $view->addScriptPath('/path/to/app/views');
 135 $view->addScriptPath('/path/to/custom/');
 136
 137 // now when you call $view->render('booklist.php'), Zend_View will
 138 // look first for "/path/to/custom/booklist.php", then for
 139 // "/path/to/app/views/booklist.php", and finally in the current
 140 // directory for "booklist.php".
 141 ]]></programlisting>
 142
 143         <note>
 144             <title>Never use user input to set script paths</title>
 145
 146             <para>
 147                 <classname>Zend_View</classname> uses script paths to lookup and render
 148                 view scripts. As such, these directories should be known
 149                 before-hand, and under your control. <emphasis>Never</emphasis>
 150                 set view script paths based on user input, as you can
 151                 potentially open yourself up to Local File Inclusion
 152                 vulnerability if the specified path includes parent directory
 153                 traversals. For example, the following input could trigger the
 154                 issue:
 155             </para>
 156
 157             <programlisting language="php"><![CDATA[
 158 // $_GET['foo'] == '../../../etc'
 159 $view->addScriptPath($_GET['foo']);
 160 $view->render('passwd');
 161 ]]></programlisting>
 162
 163             <para>
 164                 While this example is contrived, it does clearly show the
 165                 potential issue. If you <emphasis>must</emphasis> rely on user
 166                 input to set your script path, properly filter the input and
 167                 check to ensure it exists under paths controlled by your
 168                 application.
 169             </para>
 170         </note>
 171     </sect2>
 172 </sect1>
 173 <!--
 174 vim:se ts=4 sw=4 et:
 175 -->