| blob | 3336fea9619b8edaa96ee7aa7fee02f148573087 |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- EN-Revision: 17597 -->
3 <!-- Reviewed: no -->
4 <sect1 id="zend.controller.request">
5 <title>La solicitud del Objeto</title>
6 <sect2 id="zend.controller.request.introduction">
7 <title>Introducción</title>
8 <para>
9 El objeto request es un objeto de valor simple que es pasado
10 entre
11 <classname>Zend_Controller_Front</classname>
12 y el router,
13 dispatcher, y clases de controlador. Empaqueta los nombres del
14 módulo
15 solicitado, controlador, acción, y los parámetros opcionales,
16 así como el resto del
17 entorno de la solicitud, ya sea
18 <acronym>HTTP</acronym>
19 , el
20 <acronym>CLI</acronym>
21 , o
22 <acronym>PHP</acronym>
23 -GTK.
24 </para>
26 <itemizedlist>
27 <listitem>
28 <para>
29 El nombre del módulo es accedido por
30 <methodname>getModuleName()</methodname>
31 y
32 <methodname>setModuleName()</methodname>
33 .
34 </para>
35 </listitem>
37 <listitem>
38 <para>
39 El nombre del controlador es accedido por
40 <methodname>getControllerName()</methodname>
41 y
42 <methodname>setControllerName()</methodname>
43 .
44 </para>
45 </listitem>
47 <listitem>
48 <para>
49 El nombre de la acción que llamar dentro del controlador
50 es accedido por
51 <methodname>getActionName()</methodname>
52 y
53 <methodname>setActionName()</methodname>
54 .
55 </para>
56 </listitem>
58 <listitem>
59 <para>
60 Los parámetros accesibles por la acción son un array
61 asociativo de pares
62 clave/valor que son recuperados por
63 <methodname>getParams()</methodname>
64 y configurados con
65 <methodname>setParams()</methodname>
66 , o configurados
67 individualmente por
68 <methodname>getParam()</methodname>
69 y
70 <methodname>setParam()</methodname>
71 .
72 </para>
73 </listitem>
74 </itemizedlist>
76 <para>
77 Basado en el tipo de solicitud, puede haber más métodos
78 disponibles. La solicitud por
79 defecto usada,
80 <classname>Zend_Controller_Request_Http</classname>
81 , por
82 ejemplo, tiene métodos para recuperar la
83 <acronym>URI</acronym>
84 de
85 la solicitud, ruta de la información, parámetros
86 <varname>$_GET</varname>
87 y
88 <varname>$_POST</varname>
89 , etc.
90 </para>
92 <para>El objeto request es pasado al controlador front, o si no es
93 provisto, es instanciado
94 al principio del proceso dispatcher, antes
95 de que ocurra el enrutamiento. Es pasado a
96 través de todos los
97 objetos en la cadena del dispatcher.</para>
99 <para>
100 Adicionalmente, la solicitud objeto es particularmente útil en
101 pruebas. El desarrolador
102 puede cambiar el entorno de la solicitud,
103 incluyendo módulos, controladores, acciones,
104 parámetros,
105 <acronym>URI</acronym>
106 , etc, y pasar la solicitud objeto al
107 controlador front para probar el flujo de la
108 aplicación. Cuando se
109 vincula con el
110 <link linkend="zend.controller.response">objeto
111 respuesta </link>
112 , es posible elaborar y precisar una unidad de
113 pruebas de aplicaciones
114 <acronym>MVC</acronym>
115 .
116 </para>
117 </sect2>
119 <sect2 id="zend.controller.request.http">
120 <title>Solicitud HTTP</title>
122 <sect3 id="zend.controller.request.http.dataacess">
123 <title>Solicitud de acceso a datos</title>
125 <para>
126 <classname>Zend_Controller_Request_Http</classname>
127 encapsula el
128 acceso a relevantes valores tal como el nombre de la llave y el
129 valor
130 para el controlador y variables de aación enrutamiento y
131 todos los parámetros
132 adicionales analizados desde el
133 <acronym>URI</acronym>
134 . Adiccionalmente permite el acceso a
135 valores contenidos en las superglobales como
136 miembros públicos y
137 administra la actual base
138 <acronym>URL</acronym>
139 y la solicitud
140 <acronym>URI</acronym>
141 . los valores Superglobales no pueden
142 ser determinados en una solicitud objeto, en
143 vez usar los
144 métodos
145 <methodname>setParam()</methodname>
146 y
147 <methodname>getParam()</methodname>
148 para determinar o
149 recuperar los parámetros del usuario.
150 </para>
152 <note>
153 <title>Datos Superglobales</title>
154 <para>
155 Cuando se accede a datos Superglobales a través
156 <classname>Zend_Controller_Request_Http</classname>
157 como
158 propiedades de miembros públicos, es necesario mantener en
159 mente que el
160 nombre de la propiedad (supergloabl array key)
161 corresponda a una supergloabl en
162 un específico orden de
163 precedencia:1.
164 <constant>GET</constant>
165 , 2.
166 <constant>POST</constant>
167 , 3.
168 <constant>COOKIE</constant>
169 , 4.
170 <constant>SERVER</constant>
171 , 5.
172 <constant>ENV</constant>
173 .
174 </para>
175 </note>
177 <para>
178 Las supergloables específicas pueden ser accedidas usando un
179 método público como una
180 alternativa. Por ejemplo, el valor
181 original de
182 <varname>$_POST['user']</varname>
183 puede ser accedido
184 llamando a
185 <methodname>getPost('user')</methodname>
186 en la
187 solicitud objeto. Esto incluye
188 <methodname>getQuery()</methodname>
189 para recuperar elementos
190 <varname>$_GET</varname>
191 , y
192 <methodname>getHeader()</methodname>
193 para recuperar la
194 solicitud de los encabezadores (headers).
195 </para>
197 <note>
198 <title>Datos GET y POST</title>
199 <para>Sea cauteloso cuando accede a los datos de la solicitud
200 objeto como no es
201 filtrado en ninguna manera. El router y
202 dispatcher valida y filtra datos para
203 usar con sus tareas,
204 pero dejan los datos intactos en la solicitud objeto.
205 </para>
206 </note>
208 <note>
209 <title>Recuperando los datos POST sin procesar</title>
211 <para>
212 Como 1.5.0, se puede recuperar los datos sin procesar a
213 través del método
214 <methodname>getRawBody()</methodname>
215 .
216 Este método retorna falso si los datos han sido enviados de
217 esa manera, pero si
218 no retorna el cuerpo entero del post.
219 </para>
221 <para>
222 Esto es primordialmente útil para aceptar el contenido
223 cuando se desarrolla una
224 aplicación
225 <acronym>MVC</acronym>
226 simple.
227 </para>
228 </note>
230 <para>
231 Usted puede determinar parámetros de usuario en la solicitud
232 objeto usando
233 <methodname>setParam()</methodname>
234 y recuperar
235 los mismos despues usando
236 <methodname>getParam()</methodname>
237 .
238 El router hace uso de esta funcionalidad para determinar
239 parámetros correspondientes
240 en la solicitud
241 <acronym>URI</acronym>
242 a la solicitud objeto.
243 </para>
245 <note>
246 <title>getParam() Recupera mas que Parámetros de Usuario</title>
248 <para>
249 En orden para hacer el mismo trabajo,
250 <methodname>getParam()</methodname>
251 recupera actualmente
252 desde muchas fuentes. En orden de prioridad, estas incluyen:
253 parámetros de usuario determinados a través de
254 <methodname>setParam()</methodname>
255 , parámetros
256 <constant>GET</constant>
257 , y finalmente parámetros
258 <constant>POST</constant>
259 . Ser conciente de esto cuando
260 se sacan datos a través de este método.
261 </para>
263 <para>
264 Si se desea sacar solo desde parámetros se configura a
265 través de
266 <methodname>setParam()</methodname>
267 , use
268 <methodname>getUserParam()</methodname>
269 .
270 </para>
272 <para>
273 Además, a partir de 1.5.0, puede bloquear el parámetro
274 que se buscará en las
275 fuentes.
276 <methodname>setParamSources()</methodname>
277 le permite
278 especificar un array vacío o un array con uno o más de los
279 valores
280 '_GET' o '_POST', indicando que fuente de parámetro
281 se permite (por defecto,
282 ambos son permitidos); si se desea
283 restringir el acceso a solamente '_GET'
284 especificar
285 <methodname>setParamSources
286 (array('_GET'))</methodname>
287 .
288 </para>
289 </note>
291 <note>
292 <title>Apache Quirks</title>
293 <para>
294 Si está usando Apache 404 handler para pasar If you are
295 using Apache's 404
296 handler to pass incoming requests to the
297 front controller, or using a PT flag
298 with rewrite rules,
299 <varname>$_SERVER['REDIRECT_URL']</varname>
300 contains the
301 <acronym>URI</acronym>
302 you need, not
303 <varname>$_SERVER['REQUEST_URI']</varname>
304 . If you are
305 using such a setup and getting invalid routing, you should
306 use the
307 <classname>Zend_Controller_Request_Apache404</classname>
308 class instead of the default
309 <acronym>HTTP</acronym>
310 class for your request
311 object:
312 </para>
314 <programlisting language="php"><![CDATA[
315 $request = new Zend_Controller_Request_Apache404();
316 $front->setRequest($request);
317 ]]></programlisting>
319 <para>
320 This class extends the
321 <classname>Zend_Controller_Request_Http</classname>
322 class and simply modifies the autodiscovery of the request
323 URI. It can be used as
324 a drop-in replacement.
325 </para>
326 </note>
327 </sect3>
329 <sect3 id="zend.controller.request.http.baseurl">
330 <title>Base Url and Subdirectories</title>
332 <para>
333 <classname>Zend_Controller_Request_Http</classname>
334 allows
335 <classname>Zend_Controller_Router_Rewrite</classname>
336 to be
337 used in subdirectories.
338 <classname>Zend_Controller_Request_Http</classname>
339 will
340 attempt to automatically detect your base
341 <acronym>URL</acronym>
342 and set it accordingly.
343 </para>
345 <para>
346 For example, if you keep your
347 <filename>index.php</filename>
348 in a webserver subdirectory named
349 <filename>/projects/myapp/index.php</filename>
350 , base
351 <acronym>URL</acronym>
352 (rewrite base) should be set to
353 <filename>/projects/myapp</filename>
354 . This string will
355 then be stripped from the beginning of the path before
356 calculating
357 any route matches. This frees one from the necessity
358 of prepending it to any of your
359 routes. A route of
360 <command>'user/:username'</command>
361 will match
362 <acronym>URI</acronym>
363 s like
364 <filename>http://localhost/projects/myapp/user/martel</filename>
365 and
366 <filename>http://example.com/user/martel</filename>
367 .
368 </para>
370 <note>
371 <title>URL Detection is Case Sensitive</title>
372 <para>
373 Automatic base
374 <acronym>URL</acronym>
375 detection is case
376 sensitive, so make sure your
377 <acronym>URL</acronym>
378 will
379 match a subdirectory name in a filesystem (even on Windows
380 machines). If it
381 doesn't, an exception will be raised.
382 </para>
383 </note>
385 <para>
386 Should base
387 <acronym>URL</acronym>
388 be detected incorrectly
389 you can override it with your own base path with the help of
390 the
391 <methodname>setBaseUrl()</methodname>
392 method of either the
393 <classname>Zend_Controller_Request_Http</classname>
394 class,
395 or the
396 <classname>Zend_Controller_Front</classname>
397 class. The
398 easiest method is to set it in
399 <classname>Zend_Controller_Front</classname>
400 , which will
401 proxy it into the request object. Example usage to set a custom
402 base
403 <acronym>URL</acronym>
404 :
405 </para>
407 <programlisting language="php"><![CDATA[
408 /**
409 * Dispatch Request with custom base URL with Zend_Controller_Front.
410 */
411 $router = new Zend_Controller_Router_Rewrite();
412 $controller = Zend_Controller_Front::getInstance();
413 $controller->setControllerDirectory('./application/controllers')
414 ->setRouter($router)
415 ->setBaseUrl('/projects/myapp'); // set the base url!
416 $response = $controller->dispatch();
417 ]]></programlisting>
419 </sect3>
421 <sect3 id="zend.controller.request.http.method">
422 <title>Determining the Request Method</title>
424 <para>
425 <methodname>getMethod()</methodname>
426 allows you to determine the
427 <acronym>HTTP</acronym>
428 request method used to request the
429 current resource. Additionally, a variety of
430 methods exist that
431 allow you to get boolean responses when asking if a specific
432 type
433 of request has been made:
434 </para>
436 <itemizedlist>
437 <listitem>
438 <para>
439 <methodname>isGet()</methodname>
440 </para>
441 </listitem>
442 <listitem>
443 <para>
444 <methodname>isPost()</methodname>
445 </para>
446 </listitem>
447 <listitem>
448 <para>
449 <methodname>isPut()</methodname>
450 </para>
451 </listitem>
452 <listitem>
453 <para>
454 <methodname>isDelete()</methodname>
455 </para>
456 </listitem>
457 <listitem>
458 <para>
459 <methodname>isHead()</methodname>
460 </para>
461 </listitem>
462 <listitem>
463 <para>
464 <methodname>isOptions()</methodname>
465 </para>
466 </listitem>
467 </itemizedlist>
469 <para>
470 The primary use case for these is for creating RESTful
471 <acronym>MVC</acronym>
472 architectures.
473 </para>
474 </sect3>
476 <sect3 id="zend.controller.request.http.ajax">
477 <title>Detecting AJAX Requests</title>
479 <para>
480 <classname>Zend_Controller_Request_Http</classname>
481 has a
482 rudimentary method for detecting
483 <acronym>AJAX</acronym>
484 requests:
485 <methodname>isXmlHttpRequest()</methodname>
486 . This
487 method looks for an
488 <acronym>HTTP</acronym>
489 request header
490 <emphasis>X-Requested-With</emphasis>
491 with the value
492 'XMLHttpRequest'; if found, it returns
493 <constant>TRUE</constant>
494 .
495 </para>
497 <para>Currently, this header is known to be passed by default with
498 the following JS
499 libraries:</para>
501 <itemizedlist>
502 <listitem>
503 <para>Prototype/Scriptaculous (and libraries derived from
504 Prototype)</para>
505 </listitem>
506 <listitem>
507 <para>Yahoo! UI Library</para>
508 </listitem>
509 <listitem>
510 <para>jQuery</para>
511 </listitem>
512 <listitem>
513 <para>MochiKit</para>
514 </listitem>
515 </itemizedlist>
517 <para>
518 Most
519 <acronym>AJAX</acronym>
520 libraries allow you to send
521 custom
522 <acronym>HTTP</acronym>
523 request headers; if your library does not send this
524 header, simply add it as a
525 request header to ensure the
526 <methodname>isXmlHttpRequest()</methodname>
527 method works for
528 you.
529 </para>
530 </sect3>
531 </sect2>
533 <sect2 id="zend.controller.request.subclassing">
534 <title>Subclassing the Request Object</title>
536 <para>
537 The base request class used for all request objects is the
538 abstract class
539 <classname>Zend_Controller_Request_Abstract</classname>
540 . At its
541 most basic, it defines the following methods:
542 </para>
544 <programlisting language="php"><![CDATA[
545 abstract class Zend_Controller_Request_Abstract
546 {
547 /**
548 * @return string
549 */
550 public function getControllerName();
552 /**
553 * @param string $value
554 * @return self
555 */
556 public function setControllerName($value);
558 /**
559 * @return string
560 */
561 public function getActionName();
563 /**
564 * @param string $value
565 * @return self
566 */
567 public function setActionName($value);
569 /**
570 * @return string
571 */
572 public function getControllerKey();
574 /**
575 * @param string $key
576 * @return self
577 */
578 public function setControllerKey($key);
580 /**
581 * @return string
582 */
583 public function getActionKey();
585 /**
586 * @param string $key
587 * @return self
588 */
589 public function setActionKey($key);
591 /**
592 * @param string $key
593 * @return mixed
594 */
595 public function getParam($key);
597 /**
598 * @param string $key
599 * @param mixed $value
600 * @return self
601 */
602 public function setParam($key, $value);
604 /**
605 * @return array
606 */
607 public function getParams();
609 /**
610 * @param array $array
611 * @return self
612 */
613 public function setParams(array $array);
615 /**
616 * @param boolean $flag
617 * @return self
618 */
619 public function setDispatched($flag = true);
621 /**
622 * @return boolean
623 */
624 public function isDispatched();
625 }
626 ]]></programlisting>
628 <para>La solicitud objeto es un contenedor para entorno de la
629 solicitud. La cadena del
630 controlador sólo necesita saber cómo
631 establecer y recuperar el controlador, la acción,
632 los parámetros
633 opcionales, y el estado del despachador. Por defecto, la solicitud
634 buscará
635 sus propios parámetros mediante el controlador o las llaves
636 de la acción con el fin de
637 determinar el controlador y la acción.</para>
639 <para>
640 Para ampliar esta clase, o uno de sus derivados, cuando se
641 necesita la clase solicitud
642 que interactue con un entorno específico
643 con el fin de recuperar los datos para su uso en
644 las tareas antes
645 descritas. Los ejemplos incluyen
646 <link linkend="zend.controller.request.http">
647 el entorno
648 <acronym>HTTP</acronym>
649 </link>
650 , un entorno
651 <acronym>CLI</acronym>
652 , o un entorno de
653 <acronym>PHP</acronym>
654 -GTK.
655 </para>
656 </sect2>
657 </sect1>