move-uploaded-file.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xml:id="function.move-uploaded-file" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>move_uploaded_file</refname>
  <refpurpose>Moves an uploaded file to a new location</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>move_uploaded_file</methodname>
   <methodparam><type>string</type><parameter>from</parameter></methodparam>
   <methodparam><type>string</type><parameter>to</parameter></methodparam>
  </methodsynopsis>
  <para>
   This function checks to ensure that the file designated by
   <parameter>from</parameter> is a valid upload file (meaning
   that it was uploaded via PHP's HTTP POST upload mechanism). If
   the file is valid, it will be moved to the filename given by
   <parameter>to</parameter>.
  </para>
  <para>
   This sort of check is especially important if there is any chance
   that anything done with uploaded files could reveal their
   contents to the user, or even to other users on the same
   system.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>from</parameter></term>
     <listitem>
      <para>
       The filename of the uploaded file.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>to</parameter></term>
     <listitem>
      <para>
       The destination of the moved file.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns &true; on success.
  </para>
  <para>
   If <parameter>from</parameter> is not a valid upload file,
   then no action will occur, and
   <function>move_uploaded_file</function> will return
   &false;.
  </para>
  <para>
   If <parameter>from</parameter> is a valid upload file, but
   cannot be moved for some reason, no action will occur, and
   <function>move_uploaded_file</function> will return
   &false;. Additionally, a warning will be issued.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Uploading multiple files</title>
    <programlisting role="php">
<![CDATA[
<?php
$uploads_dir = '/uploads';
foreach ($_FILES["pictures"]["error"] as $key => $error) {
    if ($error == UPLOAD_ERR_OK) {
        $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
        // basename() may prevent filesystem traversal attacks;
        // further validation/sanitation of the filename may be appropriate
        $name = basename($_FILES["pictures"]["name"][$key]);
        move_uploaded_file($tmp_name, "$uploads_dir/$name");
    }
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    <function>move_uploaded_file</function> is
    <link linkend="ini.open-basedir">open_basedir</link>
    aware. However, restrictions are placed only on the
    <parameter>to</parameter> path as to allow the moving
    of uploaded files in which <parameter>from</parameter> may conflict
    with such restrictions. <function>move_uploaded_file</function> ensures
    the safety of this operation by allowing only those files uploaded
    through PHP to be moved.
   </para>
  </note>
  <warning>
   <para>
    If the destination file already exists, it will be overwritten.
   </para>
  </warning>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>is_uploaded_file</function></member>
    <member><function>rename</function></member>
    <member>See <link linkend="features.file-upload">Handling file uploads</link> for a simple usage example</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
-->