documentation/manual/es/module_specs/Zend_Db_Statement.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2     <!-- EN-Revision: 17987 -->
   3     <!-- Reviewed: no -->
   4 <sect1 id="zend.db.statement">
   5
   6     <title>Zend_Db_Statement</title>
   7
   8     <para> Además de algunos métodos convenientes tales como
   9             <methodname>fetchAll()</methodname> e
  10             <methodname>insert()</methodname> documentados en <xref
  11             linkend="zend.db.adapter"/> , puede usarse un objeto de declaración
  12         para obtener más opciones al ejecutar consultas y devolver conjuntos de
  13         resultados. Esta sección describe cómo obtener una instancia de un
  14         objeto de declaración y cómo usar sus métodos. </para>
  15
  16     <para>
  17         <classname>Zend_Db_Statement</classname> está basado en el objeto
  18         PDOStatement en la extensión <ulink url="http://www.php.net/pdo">PHP
  19             Data Objects</ulink> . </para>
  20
  21     <sect2 id="zend.db.statement.creating">
  22
  23         <title>Creando una Declaración</title>
  24
  25         <para> Típicamente, un objeto de declaración statement es devuelto por
  26             el método <methodname>query()</methodname> de la clase de Adaptador
  27             de la base de datos. Este método es un modo general de preparar una
  28             declaración <acronym>SQL</acronym> . El primer parámetro es un
  29             string conteniendo la declaración <acronym>SQL</acronym> . El
  30             segundo parámetro (opcional) es un array de valores para vincular
  31             posiciones de parámetros en el string <acronym>SQL</acronym> . </para>
  32
  33         <example id="zend.db.statement.creating.example1">
  34             <title>Crear un objeto de declaración SQL con query()</title>
  35             <programlisting language="php"><![CDATA[
  36 $stmt = $db->query(
  37             'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?',
  38             array('goofy', 'FIXED')
  39         );
  40 ]]></programlisting>
  41         </example>
  42
  43         <para> El objeto de declaración corresponde a una declaración
  44                 <acronym>SQL</acronym> que ha sido preparada y ejecutada una vez
  45             con valores vinculados especificados. Si la declaración fue una
  46             consulta SELECT u otro tipo de declaración que devuelve un conjunto
  47             de resultados, ahora estará lista para extraer resultados. </para>
  48
  49         <para> Puede crear una declaración con su constructor, pero éste es un
  50             uso menos típico. No hay un método factory para crear el objeto, así
  51             que es necesario cargar una clase de declaración específica y llamar
  52             a su constructor. Pase el objeto Adaptador como el primer parámetro,
  53             y un string conteniendo la declaración <acronym>SQL</acronym> como
  54             el segundo parámetro. La declaración es preparada pero no ejecutada. </para>
  55
  56         <example id="zend.db.statement.creating.example2">
  57             <title>Usando un constructor de declaración SQL</title>
  58             <programlisting language="php"><![CDATA[
  59 $sql = 'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?';
  60
  61 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
  62 ]]></programlisting>
  63         </example>
  64
  65     </sect2>
  66
  67     <sect2 id="zend.db.statement.executing">
  68
  69         <title>Ejecutando la declaración</title>
  70
  71         <para> Necesita ejecutar un objeto de declaración si lo crea con el
  72             constructor, o si desea ejecutar la misma declaración varias veces.
  73             Use el método <methodname>execute()</methodname> del mismo objeto de
  74             declaración. El único parámetro es un array de valores a vincular a
  75             posiciones de parámetros en la declaración. </para>
  76
  77         <para> Si usa <emphasis>parámetros posicionales</emphasis> , o los que
  78             están marcados por un signo de interrogación (
  79                 <emphasis>?</emphasis> ), pase los valores de vinculación en un
  80             array plano. </para>
  81
  82         <example id="zend.db.statement.executing.example1">
  83             <title>Ejecutar una declaración con parámetros posicionales</title>
  84             <programlisting language="php"><![CDATA[
  85 $sql = 'SELECT * FROM bugs WHERE reported_by = ? AND bug_status = ?';
  86
  87 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
  88
  89 $stmt->execute(array('goofy', 'FIXED'));
  90 ]]></programlisting>
  91         </example>
  92
  93         <para> Si usa <emphasis>parámetros nombrados</emphasis> , o los que son
  94             indicados por un string identificador precedido por un caracter de
  95             dos puntos ( <emphasis>:</emphasis> ), pase el valor en un array
  96             asociativo. Las claves de este array deben coincidir con el nombre
  97             de los parámetros. </para>
  98
  99         <example id="zend.db.statement.executing.example2">
 100             <title>Ejecutando una declaración con parámetros nombrados</title>
 101             <programlisting language="php"><![CDATA[
 102 $sql = 'SELECT * FROM bugs WHERE ' .
 103        'reported_by = :reporter AND bug_status = :status';
 104
 105 $stmt = new Zend_Db_Statement_Mysqli($db, $sql);
 106
 107 $stmt->execute(array(':reporter' => 'goofy', ':status' => 'FIXED'));
 108 ]]></programlisting>
 109         </example>
 110
 111         <para> Las declaraciones <acronym>PDO</acronym> soportan tanto
 112             parámetros posicionales como parámetros nombrados, pero no ambos
 113             tipos en la misma declaración <acronym>SQL</acronym> . Algunas
 114             clases <classname>Zend_Db_Statement</classname> para extensiones
 115             no-PDO soportan solo un tipo de parámetro o el otro. </para>
 116
 117     </sect2>
 118
 119     <sect2 id="zend.db.statement.fetching">
 120
 121         <title> Extrayendo Resultados de una declaración SELECT </title>
 122
 123         <para> Puede llamar a métodos del objeto de declaración para obtener
 124             filas desde declaraciones <acronym>SQL</acronym> que producen
 125             conjuntos de resultados. SELECT, SHOW, DESCRIBE y EXPLAIN son
 126             ejemplos de declaraciones que producen un conjunto de resultados.
 127             INSERT, UPDATE, and DELETE son ejemplo de declaraciones que no
 128             producen un conjunto de resultados. Puede ejecutar las últimas
 129             declaraciones de <acronym>SQL</acronym> usando
 130                 <classname>Zend_Db_Statement</classname> , pero no puede llamar
 131             a los métodos que extraen filas de resultados desde éste. </para>
 132
 133         <sect3 id="zend.db.statement.fetching.fetch">
 134
 135             <title>Extrayendo una Fila Simple desde un Conjunto de
 136                 Resultados</title>
 137
 138             <para> Para extraer una fila desde el conjunto de resultados, use el
 139                 método <methodname>fetch()</methodname> del objeto de
 140                 declaración. Los tres parámetros de este método son opcionales: </para>
 141
 142             <itemizedlist>
 143                 <listitem>
 144                     <para>
 145                         <emphasis>Estilo de Extracción</emphasis> es el primer
 146                         parámetro. Éste controla la estructura en la que será
 147                         devuelta la fila. Vea <xref
 148                             linkend="zend.db.adapter.select.fetch-mode"/> para
 149                         la descripción de un valor válido los correspondientes
 150                         formatos de datos. </para>
 151                 </listitem>
 152                 <listitem>
 153                     <para>
 154                         <emphasis>Orientación del Cursor</emphasis> es el
 155                         segundo parámetro. Por omisión es
 156                         Zend_Db::FETCH_ORI_NEXT, lo cual simplemente significa
 157                         que cada llamada a <methodname>fetch()</methodname>
 158                         devuelve la siguiente fila del resultado, en el orden
 159                         devuelto por el <acronym>RDBMS</acronym> . </para>
 160                 </listitem>
 161                 <listitem>
 162                     <para>
 163                         <emphasis>Compensación</emphasis> es el tercer
 164                         parámetro. Si la orientación del cursor es
 165                         Zend_Db::FETCH_ORI_ABS, entonces el offset es el número
 166                         ordinal de las filas que devolver. Si la orientación del
 167                         cursor es Zend_Db::FETCH_ORI_REL, entonces el offset es
 168                         relativo a la posición del cursor antes de que
 169                             <methodname>fetch()</methodname> fuera llamado.
 170                     </para>
 171                 </listitem>
 172             </itemizedlist>
 173
 174             <para>
 175                 <methodname>fetch()</methodname> devuelve
 176                     <constant>FALSE</constant> si todas las filas del conjunto
 177                 de resultados han sido extraídas. </para>
 178
 179             <example id="zend.db.statement.fetching.fetch.example">
 180                 <title>Usando fetch() en un bucle</title>
 181                 <programlisting language="php"><![CDATA[
 182 $stmt = $db->query('SELECT * FROM bugs');
 183
 184 while ($row = $stmt->fetch()) {
 185     echo $row['bug_description'];
 186 }
 187 ]]></programlisting>
 188             </example>
 189
 190             <para> Vea también <ulink
 191                     url="http://www.php.net/PDOStatement-fetch"
 192                     >PDOStatement::fetch()</ulink> . </para>
 193
 194         </sect3>
 195
 196         <sect3 id="zend.db.statement.fetching.fetchall">
 197
 198             <title>Extrayendo un Conjunto de Resultados completo</title>
 199
 200             <para> Para extraer todas las filas de un resultado en un solo paso,
 201                 use el método <methodname>fetchAll()</methodname> . Esto es
 202                 equivalente a llamar al método <methodname>fetch()</methodname>
 203                 en un bucle devolviendo todas las filas en una array. El método
 204                     <methodname>fetchAll()</methodname> acepta 2 parámetros. El
 205                 primero es el estilo de extracción, descrito anteriormente, y el
 206                 segundo indica el número de la columa que devolver, cuando el
 207                 estilo de extracción es Zend_Db::FETCH_COLUMN. </para>
 208
 209             <example id="zend.db.statement.fetching.fetchall.example">
 210                 <title>Usando fetchAll()</title>
 211                 <programlisting language="php"><![CDATA[
 212 $stmt = $db->query('SELECT * FROM bugs');
 213
 214 $rows = $stmt->fetchAll();
 215
 216 echo $rows[0]['bug_description'];
 217 ]]></programlisting>
 218             </example>
 219
 220             <para> Vea también <ulink
 221                     url="http://www.php.net/PDOStatement-fetchAll"
 222                     >PDOStatement::fetchAll()</ulink> . </para>
 223
 224         </sect3>
 225
 226         <sect3 id="zend.db.statement.fetching.fetch-mode">
 227
 228             <title>Cambiando el Modo de extracción</title>
 229
 230             <para> Por defecto, el objeto de declaración devuelve filas de un
 231                 conjunto de resultados como array asociativo, mapeando los
 232                 nombres de columnas a los valores de la columna. Se puede
 233                 especificar un formato diferente para que la clase de
 234                 declaración devuelva las filas, tal como se puede con la clase
 235                 Adaptadora. Puede usar él método
 236                     <methodname>setFetchMode()</methodname> para establecer el
 237                 modo de extracción. Especifique el modo de extracción usando las
 238                 constantes de la clase Zend_Db: FETCH_ASSOC, FETCH_NUM,
 239                 FETCH_BOTH, FETCH_COLUMN, and FETCH_OBJ. Vea <xref
 240                     linkend="zend.db.adapter.select.fetch-mode"/> para más
 241                 información de estos modos. Llamadas subsiguientes a los métodos
 242                 de la declaración <methodname>fetch()</methodname> o
 243                     <methodname>fetchAll()</methodname> usan el modo de
 244                 extracción especificado. </para>
 245
 246             <example id="zend.db.statement.fetching.fetch-mode.example">
 247                 <title>Configurando un modo de extracción</title>
 248                 <programlisting language="php"><![CDATA[
 249 $stmt = $db->query('SELECT * FROM bugs');
 250
 251 $stmt->setFetchMode(Zend_Db::FETCH_NUM);
 252
 253 $rows = $stmt->fetchAll();
 254
 255 echo $rows[0][0];
 256 ]]></programlisting>
 257             </example>
 258
 259             <para> Vea también <ulink
 260                     url="http://www.php.net/PDOStatement-setFetchMode"
 261                     >PDOStatement::setFetchMode()</ulink> . </para>
 262
 263         </sect3>
 264
 265         <sect3 id="zend.db.statement.fetching.fetchcolumn">
 266
 267             <title>Extrayendo una Única Columna desde un Conjunto de
 268                 Resultados</title>
 269
 270             <para> Para devolver una única columna de la siguiente fila del
 271                 conjunto de resultados, use
 272                     <methodname>fetchColumn()</methodname> . El parámetro
 273                 opcional es el índice de la columna (integer), y por defecto es
 274                 0. Este método devuelve un valor escalar, o
 275                     <constant>FALSE</constant> si todas las filas del conjunto
 276                 de resultados han sido extraídas. </para>
 277
 278             <para> Note que este método opera diferente que el método
 279                     <methodname>fetchCol()</methodname> de la clase Adaptadora.
 280                 El método <methodname>fetchColumn()</methodname> de una
 281                 declaración devuelve un único valor desde una fila. El método
 282                     <methodname>fetchCol()</methodname> de un adaptador devuelve
 283                 un array de valores, tomados desde la primera columa de todas
 284                 las del conjunto de resultados. </para>
 285
 286             <example id="zend.db.statement.fetching.fetchcolumn.example">
 287                 <title>Usando fetchColumn()</title>
 288                 <programlisting language="php"><![CDATA[
 289 $stmt = $db->query('SELECT bug_id, bug_description, bug_status FROM bugs');
 290
 291 $bug_status = $stmt->fetchColumn(2);
 292 ]]></programlisting>
 293             </example>
 294
 295             <para> Vea también <ulink
 296                     url="http://www.php.net/PDOStatement-fetchColumn"
 297                     >PDOStatement::fetchColumn()</ulink> . </para>
 298
 299         </sect3>
 300
 301         <sect3 id="zend.db.statement.fetching.fetchobject">
 302
 303             <title>Extrayendo una Fila como un Objeto</title>
 304
 305             <para> Para extraer una fila desde un conjunto de resultados
 306                 estructurado como un Objeto, use el método
 307                     <methodname>fetchObject()</methodname> . Este método tiene 2
 308                 parámetros opcionales. El primer parámetro es un string con el
 309                 nombre de la clase del objeto que devolver; por defecto será
 310                 'stdClass'. El segundo parámetro es un array de valores que será
 311                 pasado al constructor de la clase. </para>
 312
 313             <example id="zend.db.statement.fetching.fetchobject.example">
 314                 <title>Usando fetchObject()</title>
 315                 <programlisting language="php"><![CDATA[
 316 $stmt = $db->query('SELECT bug_id, bug_description, bug_status FROM bugs');
 317
 318 $obj = $stmt->fetchObject();
 319
 320 echo $obj->bug_description;
 321 ]]></programlisting>
 322             </example>
 323
 324             <para> Vea también <ulink
 325                     url="http://www.php.net/PDOStatement-fetchObject"
 326                     >PDOStatement::fetchObject()</ulink> . </para>
 327
 328         </sect3>
 329
 330     </sect2>
 331
 332     <!--
 333         @todo: binding parameters is not working yet. <sect2 id="zend.db.statement.binding-param">
 334
 335         <title>Binding PHP Variables to Parameters</title> <para> </para> <example
 336         id="zend.db.statement.binding-param.example"> <title>Binding parameters from PHP
 337         variables</title> <programlisting language="php"><![CDATA[
 338         <?php
 339         ]]></programlisting>
 340         </example> <para> See also <ulink
 341         url="http://www.php.net/PDOStatement-bindParam">PDOStatement::bindParam()</ulink>. </para>
 342
 343         </sect2>
 344     -->
 345
 346     <!--
 347         @todo: binding columns is not working yet. <sect2 id="zend.db.statement.binding-column">
 348
 349         <title>Binding PHP Variables to Query Results</title> <para> </para> <example
 350         id="zend.db.statement.binding-column.example"> <title>Binding results to PHP
 351         variables</title>
 352         <programlisting language="php"><![CDATA[
 353         <?php
 354         ]]></programlisting>
 355         </example> <para> See also <ulink
 356         url="http://www.php.net/PDOStatement-bindColumn">PDOStatement::bindColumn()</ulink>. </para>
 357
 358         </sect2>
 359     -->
 360
 361 </sect1>