archived-doc-es/reference/pgsql/functions/pg-insert.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 39bb8a868935a56cfce438b0169e13c02c93211c Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.pg-insert" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>pg_insert</refname>
  <refpurpose>
   Inserta un array en una tabla
  </refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>PgSql\Result</type><type>string</type><type>bool</type></type><methodname>pg_insert</methodname>
   <methodparam><type>PgSql\Connection</type><parameter>connection</parameter></methodparam>
   <methodparam><type>string</type><parameter>table_name</parameter></methodparam>
   <methodparam><type>array</type><parameter>values</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>PGSQL_DML_EXEC</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>pg_insert</function> inserta los <parameter>values</parameter>
   en la tabla <parameter>table_name</parameter>.
  </para>
  <para>
   Si <parameter>flags</parameter> está especificado,
   <function>pg_convert</function> se aplica a
   <parameter>values</parameter> con los flags proporcionados.
  </para>
  <para>
   Por omisión, <function>pg_insert</function> pasa valores sin tratar.
   Los valores deben ser escapados o el flag <constant>PGSQL_DML_ESCAPE</constant>
   debe ser especificado en <parameter>flags</parameter>.
   <constant>PGSQL_DML_ESCAPE</constant> coloca comillas y escapa los parámetros/identificadores.
   Por consiguiente, los nombres de tabla/columnas se vuelven sensibles a mayúsculas y minúsculas.
  </para>
  <para>
   Tenga en cuenta que ni el escape ni las consultas preparadas pueden proteger
   consultas LIKE, JSON, arrays, Regex, etc. Estos parámetros deben ser
   tratados de acuerdo con su contexto. Es decir, escapar/validar los valores.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>connection</parameter></term>
     <listitem>
      &pgsql.parameter.connection;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>table_name</parameter></term>
     <listitem>
      <para>
       Nombre de la tabla en la que se insertarán las filas. La tabla
       <parameter>table_name</parameter> debe tener al menos tantas columnas
       como elementos tenga <parameter>values</parameter>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>values</parameter></term>
     <listitem>
      <para>
       Un &array; cuyas claves son los nombres de los campos en la tabla <parameter>table_name</parameter>,
       y cuyos valores son los valores de esos campos que serán insertados.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       Cualquier combinación de constantes entre
       <constant>PGSQL_CONV_OPTS</constant>,
       <constant>PGSQL_DML_NO_CONV</constant>,
       <constant>PGSQL_DML_ESCAPE</constant>,
       <constant>PGSQL_DML_EXEC</constant>,
       <constant>PGSQL_DML_ASYNC</constant> o
       <constant>PGSQL_DML_STRING</constant>. Si
       <constant>PGSQL_DML_STRING</constant> forma parte del parámetro
       <parameter>flags</parameter>, entonces la consulta será retornada.
       Cuando la constante <constant>PGSQL_DML_NO_CONV</constant> o la constante
       <constant>PGSQL_DML_ESCAPE</constant> está definida, no se realizará ninguna llamada a la función
       <function>pg_convert</function> internamente.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;. O retorna un &string; si <constant>PGSQL_DML_STRING</constant>
   es proporcionado a través de <parameter>flags</parameter>.
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Se lanza una <classname>ValueError</classname> cuando la tabla especificada es inválida.
  </para>
  <para>
   Se lanza una <classname>ValueError</classname> o <classname>TypeError</classname> cuando
   el valor o el tipo del campo no coincide correctamente con un tipo PostgreSQL.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.3.0</entry>
      <entry>
       Ahora lanza un error <classname>ValueError</classname> cuando la tabla especificada es inválida;
       anteriormente, se emitía un <constant>E_WARNING</constant>.
      </entry>
     </row>
     <row>
      <entry>8.3.0</entry>
      <entry>
       Ahora lanza un error <classname>ValueError</classname> o <classname>TypeError</classname>
       cuando el valor o el tipo del campo no coincide correctamente con un tipo PostgreSQL;
       anteriormente, se emitía un <constant>E_WARNING</constant>.
      </entry>
     </row>
     &pgsql.changelog.return-result-object;
     &pgsql.changelog.connection-object;
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo con <function>pg_insert</function></title>
    <programlisting role="php">
<![CDATA[
<?php
  $db = pg_connect ('dbname=foo');
  // Esto es seguro en cierta medida, ya que todos los valores son escapados
  // Sin embargo, PostgreSQL soporta JSON/arrays. Estos no son
  // seguros ni por escape ni por consultas preparadas.
  $res = pg_insert($dbconn, 'post_log', $_POST, PGSQL_DML_ESCAPE);
  if ($res) {
      echo "Los datos POSTeados han podido ser registrados con éxito.\n";
  } else {
      echo "Hay un problema con los datos.\n";
  }
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>pg_convert</function></member>
   </simplelist>
  </para>
 </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->