rafael Thu Jun 6 17:56:13 2002 EDT
Modified files:
/phpdoc-es/features file-upload.xml
Log:
Translation updated to PHP 4.x
Index: phpdoc-es/features/file-upload.xml
diff -u phpdoc-es/features/file-upload.xml:1.5 phpdoc-es/features/file-upload.xml:1.6
--- phpdoc-es/features/file-upload.xml:1.5 Wed Dec 12 15:47:53 2001
+++ phpdoc-es/features/file-upload.xml Thu Jun 6 17:56:13 2002
@@ -1,6 +1,9 @@
<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.6 $ -->
+<!-- EN-Revision: 1.38 Maintainer: pablof Status: ready -->
+
<chapter id="features.file-upload">
- <title>El envío de archivos</title>
+ <title>Manejo de envío de ficheros</title>
<sect1 id="features.file-upload.post-method">
<title>Envío de archivos con el método POST</title>
@@ -19,7 +22,10 @@
<para>
Es importante destacar que PHP también soporta el método PUT
para envío de archivos tal y como lo utiliza Netscape Composer
- y el cliente Amaya de W3C. Consulte <link
linkend="features.file-upload.put-method">Soporte del método PUT</link> para
más detalles.</para>
+ y el cliente Amaya de W3C. Consulte <link
+linkend="features.file-upload.put-method">
+ Soporte del método PUT</link> para más detalles.
+ </para>
+
<para>
Una página de envío de archivos se puede crear mediante un
formulario
@@ -28,146 +34,325 @@
<example>
<title>Formulario de envío de archivo</title>
<programlisting>
-&lt;FORM ENCTYPE=&quot;multipart/form-data&quot;
ACTION=&quot;_URL_&quot; METHOD=POST&gt;
-&lt;INPUT TYPE=&quot;hidden&quot; name=&quot;MAX_FILE_SIZE&quot;
value=&quot;1000&quot;&gt;
-Enviar este archivo: &lt;INPUT NAME=&quot;userfile&quot;
TYPE=&quot;file&quot;&gt;
-&lt;INPUT TYPE=&quot;submit&quot; VALUE=&quot;Enviar&quot;&gt;
-&lt;/FORM&gt;
- </programlisting>
+<![CDATA[
+<form enctype="multipart/form-data" action="_URL_" method="post">
+<input type="hidden" name="MAX_FILE_SIZE" value="1000">
+Send this file: <input name="userfile" type="file">
+<input type="submit" value="Send File">
+</form>
+]]>
+ </programlisting>
</example>
- La _URL_ debe tener como destino un script PHP. El campo MAX_FILE_SIZE
- debe encontrarse antes del campo INPUT y su valor determina el tamaño
- máximo de archivo que se puede enviar en bytes. Tras la recepción
del
- archivo se definirán en el script PHP destino las siguientes variables:
+ La _URL_ debe tener como destino un script PHP. El input oculto MAX_FILE_SIZE
+ debe encontrarse antes del input de tipo "file" para indicar
+ el tamaño máximo de archivo que se puede enviar en bytes
+
+ <warning>
+ <para>
+ MAX_FILE_SIZE debe ser consultado por el navegador; aun así es
+ sencillo saltarse este máximo por lo tanto no se debe presuponer
+ que el navegador siempre lo respetará. En contrapartida,
+ la configuracion de PHP relativa al tamaño maximo no puede
+ ser obviada.
+ </para>
+ </warning>
+ </para>
+
+ <para>
+ Las variables definidas para los archivos enviados varian
+ en función de la versión y configuración de PHP que se
+utilice.
+ Las variables de las que hablamos a continuación serán
+ definidas en la página destino despues de una recepción de
+fichero correcta.
+ Cuando <link linkend="ini.track-vars">track_vars</link> este activado,
+ el array $HTTP_POST_FILES/$_FILES se inicializará. Por ultimo, las
+ variables relacionadas seran inicializadas como globales cuando
+ <link linkend="ini.register-globals">register_globals</link> esté
+ habilitado. Cabe señalar que el uso de las variables globales
+ no esta recomendado en ningún caso.
+ </para>
+ <note>
+ <para>
+ <link linkend="ini.track-vars">track_vars</link> esta activado siempre
+ desde PHP 4.0.3. A partir de PHP 4.1.0 , $_FILES puede ser utilizado
+ alternativamente a <varname>$HTTP_POST_FILES</varname>.
+ <varname>$_FILES</varname> es siempre global asi que <literal>global</literal>
+ no debe ser usado con $_FILES en el ámbito de función.
+ </para>
+ </note>
+ <para>
+ <varname>$HTTP_POST_FILES</varname>/<varname>$_FILES</varname> contienen
+ la información sobre el fichero recibido.
+ </para>
+
+ <para>
+ A continuación se describe el contenido de
+ <varname>$HTTP_POST_FILES</varname>.
+ Se ha tomado el nombre 'userfile' para el fichero recibido tal y
+ como se usaba en el script de ejemplo anterior:
+ <variablelist>
+ <varlistentry>
+ <term><varname>$HTTP_POST_FILES['userfile']['name']</varname></term>
+ <listitem>
+ <para>
+ El nombre original del fichero en la máquina cliente.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>$HTTP_POST_FILES['userfile']['type']</varname></term>
+ <listitem>
+ <para>
+ El tipo mime del fichero (si el navegador lo proporciona). Un ejemplo
+ podría ser <literal>"image/gif"</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>$HTTP_POST_FILES['userfile']['size']</varname></term>
+ <listitem>
+ <para>
+ El tamaño en bytes del fichero recibido.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varname>$HTTP_POST_FILES['userfile']['tmp_name']</varname></term>
+ <listitem>
+ <para>
+ El nombre del fichero temporal que se utiliza para almacenar en el
+ servidor el archivo recibido.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ <note>
+ <para>
+ A partir de PHP 4.1.0 se puede utilizar el variable corta
+ <varname>$_FILES</varname>. PHP 3 no soporta
+ <varname>$HTTP_POST_FILES</varname>.
</para>
+ </note>
<para>
+ Cuando <link linkend="ini.register-globals">register_globals</link>
+ se activa en el &php.ini; las siguientes variables son accesibles.
+ Se ha tomado el nombre 'userfile' para el fichero recibido tal y
+ como se usaba en el script de ejemplo del principio:
+
<itemizedlist>
<listitem>
<simpara>
- $userfile - El archivo temporal que se ha guardado en el servidor.
+ <varname>$userfile</varname> - El nombre del fichero temporal que
+ se utiliza para almacenar en el servidor el archivo recibido.
</simpara>
</listitem>
<listitem>
<simpara>
- $userfile_name - El nombre original del archivo enviado.
+ <varname>$userfile_name</varname> - El nombre original del fichero
+ en la máquina cliente.
</simpara>
</listitem>
<listitem>
<simpara>
- $userfile_size - El tamaño del archivo recibido.
+ <varname>$userfile_size</varname> - El tamaño en bytes del fichero
+recibido.
</simpara>
</listitem>
<listitem>
<simpara>
- $userfile_type - El tipo mime del archivo si el navigador
- envio esta información. Por ejemplo:
- &quot;image/gif&quot;.
+ <varname>$userfile_type</varname> - El tipo mime del fichero
+ (si el navegador lo proporciona). Un ejemplo podría ser "image/gif".
</simpara>
</listitem>
</itemizedlist>
-
- Es importante recordar que la primera palabra &quot;$userfile&quot;
- de éstas variables corresponde al nombre ("NAME=") del campo
- "INPUT TYPE=file" del formulario. En el ejemplo anterior usamos
- &quot;userfile&quot;.</para>
-
- <simpara>
- Los archivos enviados serán guardados en el directorio temporal por
- defecto del servidor. Podemos variar este directorio mediante la
- variable de entorno <envar>TMPDIR</envar> en el entorno donde
- corre PHP. No se puede establecer este valor usando <function>putenv</function>
- desde un script PHP.
- </simpara>
- <simpara>
- El script PHP que recibe el archivo enviado debe implementar
- las acciones que se deben llevar a cabo con el archivo acabado
- de recibir. Por ejemplo se podria utilizar $file_size para
- decidir descartar los archivos que sean demadiado pequeños o
- demasiado grandes. Sean cual sean las acciones a tomar se debe
- borrar el archivo temporal o moverlo a algún otro directorio.
- </simpara>
+ Se puede ver que "<varname>$userfile</varname>" (en las
+ variables anteriores) toma el valor del atributo "name"
+ que contenga el campo <input> de tipo "file" del
+ formulario de envio. En el ejemplo anterior, elegimos
+ llamarlo "userfile".
+ </para>
+ <note>
+ <para>
+ <literal>register_globals = On</literal> se desaconseja por
+ razones de seguridad y rendimiento.
+ </para>
+ </note>
+ <para>
+ Por defecto, los ficheros serán almacenados en el directorio
+ temporal por defecto del servidor a no ser que se especifique
+ otra localizacion con la directiva <link
+ linkend="ini.upload-tmp-dir">upload_tmp_dir</link> en &php.ini;.
+ El directorio temporal por defecto del servidor puede ser
+ modificado cambiando el valor de la variable de entorno
+ <envar>TMPDIR</envar> en el contexto en que se ejecuta PHP
+ La configuración de las variables de entorno no se puede
+ realizar en PHP a través de la función
+<function>putenv</function>.
+ Esta variable de entorio puede ser utilizada también para
+ asegurarnos que otras operaciones con archivos recibidos están
+ funcionando correctamente.
+ <example>
+ <title>Verificando los archivos recibidos</title>
+ <para>
+ Los siguientes ejemplos son validos para versiones de PHP 4
+ superiores a la 4.0.2. Veanse las funciones
+ <function>is_uploaded_file</function> y
+ <function>move_uploaded_file</function>.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+// In PHP 4.1.0 or later, $_FILES should be used instead of $HTTP_POST_FILES.
+if (is_uploaded_file($HTTP_POST_FILES['userfile']['tmp_name'])) {
+ copy($HTTP_POST_FILES['userfile']['tmp_name'], "/place/to/put/uploaded/file");
+} else {
+ echo "Possible file upload attack. Filename: " .
+$HTTP_POST_FILES['userfile']['name'];
+}
+/* ...or... */
+move_uploaded_file($HTTP_POST_FILES['userfile']['tmp_name'],
+"/place/to/put/uploaded/file");
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
<simpara>
- El archivo recibido será eliminado inmediatamente del directorio
- temporal al finalizar el script PHP que lo recibió si no ha sido
- movido o renombrado.
+ El script PHP que recibe el fichero, debe implementar la lógica
+ necesaria para determinar que debe ser realizado con el fichero.
+ Se puede utilizar, por ejemplo, la variable
+ <varname>$HTTP_POST_FILES['userfile']['size']</varname>
+ para descartar los ficheros demasiado chicos o demasiado grandes;
+ por otro lado, se puede usar la variable
+ <varname>$HTTP_POST_FILES['userfile']['type']</varname>
+ para descartar los que no se ajusten a algun criterio de tipo.
+ Cualquiera que sea la logica que utilicemos, se debe borrar
+ o mover el archivo del directorio temporal.
+ </simpara>
+ <simpara>
+ El archivo será borrado del directorio temporal al final de la
+petición
+ si no se ha movido o renombrado.
</simpara>
</sect1>
<sect1 id="features.file-upload.common-pitfalls">
<title>Errores comunes</title>
<simpara>
- El valor de MAX_FILE_SIZE no puede ser mayor que el tamaño del archivo
- que se especifica en la variable upload_max_filesize del archivo
- PHP3.ini o la correspondiente directiva php3_upload_max_filesize de
- Apache. Por defecto es 2 Megabytes.</simpara>
- <simpara>
- El servidor CERN parece que elimina cualquier cosa antes del primer
- espacio en blanco en la cabecera mime content-type que recibe de los
- clientes. Mientras esto no varie, CERN httpd no podrá soportar el
- envío de archivos.</simpara>
+ A <literal>MAX_FILE_SIZE</literal> no se le puede dar un valor mayor que
+ el valor que se haya especificado en la directiva<link
+ linkend="ini.upload-max-filesize">upload_max_filesize</link>.
+ Por defecto se tiene un límite de 2 MegaBytes.
+ </simpara>
+ <simpara>
+ Si se ha activado el límite de memoria, se deben especificar un
+ valor alto para <link linkend="ini.memory-limit">memory_limit</link>.
+ En cualquier caso, se debe asegurar un valor suficientemente grande para
+ <link linkend="ini.memory-limit">memory_limit</link>.
+ </simpara>
+<!-- FIXME: max_execution_time INI -->
+ <simpara>
+ Si <link linkend="ini.max-execution-time">max_execution_time</link>
+ tiene un valor muy pequeño, la ejecución del script puede
+exceder este valor.
+ De esta forma, se debe asegurar un valor suficientemente grande para
+ <literal>max_execution_time</literal>.
+ </simpara>
+ <simpara>
+ Si <link linkend="ini.post-max-size">post_max_size<</link>
+ tiene un valor muy pequeño, los ficheros mas grandes a este valor, no
+podrán
+ ser enviados. Por ello, se debe asegurar un valor suficientemente grande para
+ <literal>post_max_size</literal>.
+ </simpara>
+ <simpara>
+ No verificar que ficheros se estan manipulando puede tener como consecuencia
+ que los usuarios puedan acceder a información sensible en otros
+directorios.
+ </simpara>
+ <simpara>
+ Cabe señalar que el httpd de CERN parece cortar todo a partir
+ del primer espacio en blanco en el "content-type" de la cabecera mime que
+ obtiene del cliente. Si este es el caso, con el httpd de CERN no se soporta
+ la funcionalidad de envío de ficheros.
+ </simpara>
</sect1>
- <sect1 id="feature-fileupload.multiple">
- <title>Envío de más de un archivo</title>
+ <sect1 id="features.file-upload.multiple">
+ <title>Envío de multiples ficheros</title>
<simpara>
- Es posible el envio de varios archivos simultáneamente y poder
- clasificar la información automáticamente por arrays. Esto de
- hace de la misma manera en que se organizan por arrays los
- SELECT o CHECKBOX:</simpara>
+ Se pueden enviar multiples ficheros usando diferentes
+ nombres (<literal>name</literal>) para los <literal>input</literal>.
+ </simpara>
+ <simpara>
+ Así mismo, es posible enviar varios archivos simultaneamente y tener
+ organizada en arrays la información. Para hacer esto, se utiliza la
+ misma sintáxis que cuando tenemos multiples "selects" o "checkboxes"
+ en el formulario HTML:
+ </simpara>
<note>
<para>
- El soporte para múltiple envios de archivos se añadió en la
versión 3.0.10</para>
- </note>
-
+ El soporte para envío multiple de ficheros fue añadido en
+ la versión 3.0.10.
+ </para>
+ </note>
<para>
<example>
- <title>Formulario de envío multiple de archivos</title>
- <programlisting>
-&lt;form action=&quot;file-upload.html&quot;
method=&quot;post&quot; enctype=&quot;multipart/form-data&quot;&gt;
- Enviar estos archivos:&lt;br&gt;
- &lt;input name=&quot;userfile[]&quot;
type=&quot;file&quot;&gt;&lt;br&gt;
- &lt;input name=&quot;userfile[]&quot;
type=&quot;file&quot;&gt;&lt;br&gt;
- &lt;input type=&quot;submit&quot;
value=&quot;Enviar&quot;&gt;
-&lt;/form&gt;
+ <title>Envío de multiples ficheros</title>
+ <programlisting role="html">
+<![CDATA[
+<form action="file-upload.php" method="post" enctype="multipart/form-data">
+ Send these files:<br>
+ <input name="userfile[]" type="file"><br>
+ <input name="userfile[]" type="file"><br>
+ <input type="submit" value="Send files">
+</form>
+]]>
</programlisting>
- </example></para>
-
+ </example>
+ </para>
<simpara>
- Cuando el formulario es procesado, los arrays
<computeroutput>$userfile</computeroutput>,
- <computeroutput>$userfile_name</computeroutput>, y
- <computeroutput>$userfile_size</computeroutput> se crearán de alcance
- global (igual que $HTTP_POST_VARS). Cada uno será un array con
- índice numérico con los valores apropiados para los archivos
- enviados.</simpara>
-
+
+ Cuando el formulario del ejemplo es enviado, los arrays
+ <varname>$HTTP_POST_FILES['userfile']</varname>,
+ <varname>$HTTP_POST_FILES['userfile']['name']</varname> y
+ <varname>$HTTP_POST_FILES['userfile']['size']</varname>
+ son inicializados. Así mismo pasa con $_FILES en PHP 4.1.0
+ o superiores y $HTTP_POST_VARS en PHP 3. Cuando
+ <literal>register_globals</literal> esta activa, las
+ variables globales para los archivos recibidos también son
+inicializadas.
+ Cada uno de estos arrays tendrá en los índices numericos
+correspondientes
+ los valores para cada fichero recibido.
+ </simpara>
+ <simpara>
+ Por ejemplo, si tomamos como nombres de archivo enviados
+ <filename>/home/test/review.html</filename> y
+ <filename>/home/test/xwp.out</filename>. Tendríamos en
+ <varname>$HTTP_POST_FILES['userfile']['name'][0]</varname>
+ el valor de <filename>review.html</filename>, y en
+ <varname>$HTTP_POST_FILES['userfile']['name'][1]</varname> tendríamos
+ <filename>xwp.out</filename>; analogamente,
+ <varname>$HTTP_POST_FILES['userfile']['size'][0]</varname> contendría
+ el tamaño del fichero <filename>review.html</filename>, y asi
+sucesivamente...
+ </simpara>
<simpara>
- Por ejemplo, supongamos que los siguientes archivos
- <filename>/home/test/review.html</filename> y
- <filename>/home/test/xwp.out</filename> son enviados. En este
- caso, <computeroutput>$userfile_name[0]</computeroutput> almacenaría
- el valor <computeroutput>review.html</computeroutput>, y
- <computeroutput>$userfile_name[1]</computeroutput> almacenaría el
- valor <computeroutput>xwp.out</computeroutput>. Así,
- <computeroutput>$userfile_size[0]</computeroutput> almacenaría el
- tamaño de <filename>review.html</filename> y así con los valores
- siguientes.</simpara></sect1>
+ <varname>$HTTP_POST_FILES['userfile']['name'][0]</varname>,
+ <varname>$HTTP_POST_FILES['userfile']['tmp_name'][0]</varname>,
+ <varname>$HTTP_POST_FILES['userfile']['size'][0]</varname> y
+ <varname>$HTTP_POST_FILES['userfile']['type'][0]</varname> tambien
+ son asignadas.
+ </simpara>
+ </sect1>
<sect1 id="features.file-upload.put-method">
<title>Soporte del método PUT</title>
<para>
PHP soporta el metodo HTTP PUT que usan aplicaciones como Netscape
- Composer y Amaya de W3C. Las peticiones PUT son más sencillas que
+ Composer y Amaya del W3C. Las peticiones PUT son más sencillas que
el método POST. Un ejemplo:
- <informalexample><programlisting>
+ <informalexample>
+ <programlisting>
PUT /path/filename.html HTTP/1.1
- </programlisting></informalexample>
+ </programlisting>
+ </informalexample>
</para>
-
<para>
Esto normalmente significaría que el cliente remoto quiere salvar
el contenido como: /path/filename.html en tu árbol web. Lógicamente
@@ -180,26 +365,29 @@
bloque &lt;Virtualhost&gt;. Una linia así deberia hacer ésta
función:
- <informalexample><programlisting>
-Script PUT /put.php3
- </programlisting></informalexample>
+ <informalexample>
+ <programlisting>
+Script PUT /put.php
+ </programlisting>
+ </informalexample>
</para>
-
<simpara>
- Ésto le dice a Apache que envie todas peticiones PUT para URIs que
- contengan esta linia al script put.php3. Se asume que PHP se
- encuentra activo y con la extension php3 enlazada a él.
+ Ésto le dice a Apache que envíe todas peticiones PUT para URIs que
+ contengan esta linia al script put.php. Se asume que PHP se
+ encuentra activo y con la extensión .php enlazada a él.
</simpara>
<simpara>
Dentro del script put.php3 se podría implementar algo así:
</simpara>
<para>
- <informalexample><programlisting>
-&lt;? copy($PHP_UPLOADED_FILE_NAME,$DOCUMENT_ROOT.$REQUEST_URI); ?&gt;
+ <informalexample><programlisting role="php">
+<![CDATA[
+<?php copy($PHP_UPLOADED_FILE_NAME,$DOCUMENT_ROOT.$REQUEST_URI); ?>
+]]>
</programlisting></informalexample>
</para>
<simpara>
- Esto copiaria el archivo a la localización requerida por el cliente
+ Esto copiaría el archivo a la localización requerida por el cliente
remoto. Aqui se pueden ejecutar funciones de autentificación de
usuario o cualquier otro tipo de chequeo. El archivo se guarda en
el archivo temporal del sistema servidor de la misma manera que el
@@ -208,10 +396,12 @@
consequencia el script dede proceder al trato de éste inmediatamente,
ya sea para copiarlo, renombrarlo, etc. El archivo se encuentra en
la variable $PHP_PUT_FILENAME, y el destino sugerido por el cliente
- en la variable $REQUEST_URI (puede variar en servidores diferentes de
+ en la variable $REQUEST_URI (puede variar en servidores web que no sean
Apache). No es necesario hacer caso al destino sugerido por el cliente.
Por ejemplo se podrían copiar los archivos enviados a directorios
- especialmente designados para esta tarea.</simpara></sect1>
+ especialmente designados para esta tarea.
+ </simpara>
+ </sect1>
</chapter>
@@ -226,9 +416,12 @@
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
-sgml-default-dtd-file:"../manual.ced"
+sgml-default-dtd-file:"../../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
-->