file-upload.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 3944dc63330edde959cfd3e7d113c999cbec10ff Maintainer: nikic Status: ready -->
<!-- Credits: tom, hholzgra -->
 <chapter xml:id="features.file-upload" xmlns="http://docbook.org/ns/docbook">
  <title>Steuerung von Dateiuploads</title>

  <sect1 xml:id="features.file-upload.post-method">
   <title>Dateiuploads mit POST</title>
   <simpara>
    Dieses Feature erlaubt es Benutzern sowohl Text- als auch Binärdaten
    hochzuladen. Mit PHP's Authentifizierungs- und Dateifunktionen besteht
    volle Kontrolle darüber, wer Dateien hochladen darf und was mit den
    Dateien geschehen soll, wenn das Hochladen beendet ist.
   </simpara>
   <simpara>
    PHP kann Dateiuploads von jedem RFC-1867-konformen Browser empfangen.
   </simpara>
   <note>
    <title>Diesbezügliche Konfigurationshinweise</title>
    <para>
     Siehe auch die Anweisungen
     <link linkend="ini.file-uploads">file_uploads</link>,
     <link linkend="ini.upload-max-filesize">upload_max_filesize</link>,
     <link linkend="ini.upload-tmp-dir">upload_tmp_dir</link>,
     <link linkend="ini.post-max-size">post_max_size</link> und
     <link linkend="ini.max-input-time">max_input_time</link>
     in der &php.ini;
    </para>
   </note>
   <para>
    PHP unterstützt auch das Hochladen von Dateien nach der PUT-Methode, die
    beispielsweise vom <productname>Netscape Composer</productname> und den
    W3C-<productname>Amaya</productname>-Clients verwendet wird. Siehe dazu
    <link linkend="features.file-upload.put-method">PUT-Unterstützung</link>
    für nähere Informationen.
   </para>
   <para>
    <example>
     <title>Formular zum Hochladen von Dateien</title>
     <para>
      Um Dateieuploads zu ermöglichen muss ein Formular erstellt werden,
      welches ungefähr wie folgt aussieht:
     </para>
     <programlisting role="html">
<![CDATA[
<!-- Der Kodierungstyp enctype MUSS wie dargestellt angegeben werden -->
<form enctype="multipart/form-data" action="__URL__" method="POST">
    <!-- MAX_FILE_SIZE muss vor dem Datei-Eingabefeld stehen -->
    <input type="hidden" name="MAX_FILE_SIZE" value="30000" />
    <!-- Der Name des Eingabefelds bestimmt den Namen im $_FILES-Array -->
    Diese Datei hochladen: <input name="userfile" type="file" />
    <input type="submit" value="Send File" />
</form>
]]>
     </programlisting>
     <para>
      <literal>__URL__</literal> im obigen Beispiel sollte durch die URL eines
      PHP-Skripts ersetzt werden.
     </para>
     <para>
      Das "hidden"-Feld <literal>MAX_FILE_SIZE</literal> muss dem
      "file"-Eingabefeld vorangestellt werden; der angegebene Wert bestimmt
      die maximale akzeptierte Dateigröße in Bytes. Dieses Formular-Element
      sollte immer benutzt werden, da es dem Benutzer erspart auf einen großen
      Dateiupload zu warten, nur um festzustellen, dass die Datei zu groß war
      und der Upload fehlgeschlagen ist. Es sollte jedoch beachtet werden,
      dass diese Browserseitige Einstellung sehr einfach zu umgehen ist und
      man sich daher niemals darauf verlassen sollte, dass sie übergroße
      Dateiuploads verhindert. Die Server-seitige Option für die Maximalgröße
      kann hingegen nicht umgangen werden.
     </para>
    </example>
   </para>
   <note>
    <para>
     Das Uploadformular muss unbedingt das Attribut
     <literal>enctype="multipart/form-data"</literal> angeben, andernfalls
     wird der Upload nicht funktionieren.
    </para>
   </note>
   <para>
    Die globale Variable <varname>$_FILES</varname> enthält alle Informationen
    über hochgeladene Dateien. Im Folgenden sind ihre Inhalte für das obige
    Beispielformular aufgelistet. Beachten Sie, dass dies auf der Annahme
    basiert, dass der Name des Dateiuploads wie in dem obigen Beispielskript
    <emphasis>userfile</emphasis> ist. Es kann aber auch jeder andere Name
    verwendet werden.
    <variablelist>
     <varlistentry>
      <term><varname>$_FILES['userfile']['name']</varname></term>
      <listitem>
       <para>
        Der ursprüngliche Dateiname auf dem Computer des Benutzers.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['type']</varname></term>
      <listitem>
       <para>
        Der MIME-Type der Datei, falls der Browser diese Information zur
        Verfügung gestellt hat. Ein Beispiel wäre
        <literal>"image/gif"</literal>. Dieser MIME-Type wird jedoch nicht von
        PHP geprüft und kann somit falsch sein.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['size']</varname></term>
      <listitem>
       <para>
        Die Größe der hochgeladenen Datei in Bytes.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['tmp_name']</varname></term>
      <listitem>
       <para>
        Der temporäre Dateiname, unter dem die hochgeladene Datei auf dem
        Server gespeichert wurde.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['error']</varname></term>
      <listitem>
       <para>
        Der <link linkend="features.file-upload.errors">Fehlercode</link> des
        Uploads.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><varname>$_FILES['userfile']['full_path']</varname></term>
      <listitem>
       <para>
        Der vollständige Pfad, wie er vom Browser übermittelt wurde. Dieser
        Wert enthält nicht immer eine echte Verzeichnisstruktur und ist daher
        nicht vertrauenswürdig.
        Verfügbar ab PHP 8.1.0.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    Standardmäßig werden Dateien im standardmäßigen temporären Verzeichnis des
    Servers gespeichert, außer es wurde mittels <link
    linkend="ini.upload-tmp-dir">upload_tmp_dir</link> in der &php.ini; ein
    anderer Ort konfiguriert. Das Standardverzeichnis des Servers kann durch
    das Setzen der Umgebungsvariablen <envar>TMPDIR</envar> in der Umgebung,
    in der PHP ausgeführt wird, geändert werden. Das Setzen mittels der
    Funktion <function>putenv</function> innerhalb eines Skriptes ist nicht
    möglich. Mittels dieser Umgebungsvariable kann auch sichergestellt werden,
    dass auch andere Operationen an hochgeladenen Dateien arbeiten können.
    <example>
     <title>Dateiuploads prüfen</title>
     <para>
      Weitere Informationen finden Sie auch in den Beschreibungen für
      <function>is_uploaded_file</function> und
      <function>move_uploaded_file</function>. Das folgende Beispiel
      verarbeitet einen von einem HTML-Formular kommenden Dateiupload.
     </para>
     <programlisting role="php">
<![CDATA[
<?php
$uploaddir = '/var/www/uploads/';
$uploadfile = $uploaddir . basename($_FILES['userfile']['name']);

echo '<pre>';
if (move_uploaded_file($_FILES['userfile']['tmp_name'], $uploadfile)) {
    echo "Datei ist valide und wurde erfolgreich hochgeladen.\n";
} else {
    echo "Möglicherweise eine Dateiupload-Attacke!\n";
}

echo 'Weitere Debugging Informationen:';
print_r($_FILES);

print "</pre>";

?>
]]>
     </programlisting>
    </example>
   </para>
   <simpara>
    Das die hochgeladene Datei empfangende Skript sollte die notwendige Logik
    zur Entscheidung enthalten, was mit der hochgeladenen Datei geschehen
    soll. Sie können zum Beispiel
    <varname>$_FILES['userfile']['size']</varname> verwenden, um zu kleine
    bzw. zu große Dateien wegzuwerfen. Sie können
    <varname>$_FILES['userfile']['type']</varname> nutzen, um Dateien eines
    unerwünschten Typs wegzuwerfen, sollten dabei jedoch beachten, dass dieser
    Wert vollständig vom Benutzer kontrolliert wird und somit falsch sein
    kann. Sie können Ihre Logik auch mittels
    <varname>$_FILES['userfile']['error']</varname> anhand der
    <link linkend="features.file-upload.errors">Fehlercodes</link> planen.
    Egal welche Logik Sie verwenden, Sie sollten die Datei im temporären
    Verzeichnis entweder löschen, oder an einen anderen Ort verschieben.
   </simpara>
   <simpara>
    Wenn im Formular keine Datei ausgewählt wurde so wird
    <varname>$_FILES['userfile']['size']</varname> von PHP auf 0 gesetzt und
    <varname>$_FILES['userfile']['tmp_name']</varname> ist leer.
   </simpara>
   <simpara>
    Wurde die Datei in dem temporären Verzeichnis nicht verschoben oder
    umbenannt, wird sie am Ende des Requests gelöscht.
   </simpara>
   <example>
    <title>Hochladen eines Arrays von Dateien</title>
     <para>
      PHP unterstützt <link linkend="faq.html.arrays">HTML Arrays</link>
      auch für Dateien.
     </para>
     <programlisting role="html">
<![CDATA[
<form action="" method="post" enctype="multipart/form-data">
<p>Pictures:
<input type="file" name="pictures[]" />
<input type="file" name="pictures[]" />
<input type="file" name="pictures[]" />
<input type="submit" value="Send" />
</p>
</form>
]]>
     </programlisting>
     <programlisting role="php">
<![CDATA[
<?php
foreach ($_FILES["pictures"]["error"] as $key => $error) {
    if ($error == UPLOAD_ERR_OK) {
        $tmp_name = $_FILES["pictures"]["tmp_name"][$key];
        // basename() kann Directory Traversal Angriffe verhindern; weitere
        // Gültigkeitsprüfung/Bereinigung des Dateinamens kann angebracht sein
        $name = basename($_FILES["pictures"]["name"][$key]);
        move_uploaded_file($tmp_name, "data/$name");
    }
}
?>
]]>
     </programlisting>
    </example>
   <para>
    Eine Fortschrittsanzeige für Dateiuploads kann mittels
    <link linkend="session.upload-progress">Session Upload Progress</link>
    implementiert werden.
   </para>
  </sect1>

  <sect1 xml:id="features.file-upload.errors">
   <title>Fehlermeldungen erklärt</title>
   <simpara>
    PHP gibt zusammen mit dem Datei-Array entsprechende Fehlermeldungen
    zurück. Die Fehlermeldung befindet sich im Segment
    <literal>error</literal> des Datei-Arrays, welches während des Hochladens
    der Datei erstellt wird. Mit anderen Worten: der Fehler kann in
    <varname>$_FILES['userfile']['error']</varname> gefunden werden.
   </simpara>
   <simpara>
    Der Wert dieses Fehlercodes ist eine der
    <constant>UPLOAD_ERR_<replaceable>*</replaceable></constant>-Konstanten.
   </simpara>
  </sect1>

  <sect1 xml:id="features.file-upload.common-pitfalls">
   <title>Häufige Probleme</title>
   <simpara>
    Der mit <literal>MAX_FILE_SIZE</literal> eingestellte Wert kann nicht
    größer sein als der des ini-Parameters
    <link linkend="ini.upload-max-filesize">upload_max_filesize</link>. Der
    Standardwert ist 2 Megabyte.
   </simpara>
   <simpara>
    Ist das Speicherlimit aktiviert, könnte eine Erhöhung von
    <link linkend="ini.memory-limit">memory_limit</link> nötig sein. Stellen
    Sie sicher, dass der Wert von
    <link linkend="ini.memory-limit">memory_limit</link> groß genug ist.
   </simpara>
   <simpara>
    Wenn <link linkend="ini.max-execution-time">max_execution_time</link> zu
    kurz konfiguriert ist, könnte das Skript den Wert überschritten haben.
    Stellen Sie sicher, dass der Wert von
    <literal>max_execution_time</literal> groß genug ist.
   </simpara>
   <note>
    <simpara>
     <link linkend="ini.max-execution-time">max_execution_time</link>
     beschränkt nur die Ausführungszeit des Skripts selbst. Jegliche Zeit die
     auf Dinge entfällt die außerhalb des Skripts stattfinden, wie &zb;
     Systemaufrufe mit <function>system</function>, die Funktion
     <function>sleep</function>, Datenbankabfragen und die für das Hochladen
     von Dateien benötigte Zeit werden bei der Bestimmung der Ausführungszeit
     nicht mit einbezogen.
    </simpara>
   </note>
   <warning>
    <simpara>
     <link linkend="ini.max-input-time">max_input_time</link> legt die
     maximale Zeit in Sekunden fest während der es einem Skript gestattet ist
     Eingaben zu empfangen. Diese beinhaltet auch die für das Hochladen von
     Dateien benötigte Zeit. Werden viele oder große Dateien übertragen oder
     ist die Verbindung zum Benutzer langsam, so kann die Standardeinstellung
     von <literal>60</literal> Sekunden überschritten werden.
    </simpara>
   </warning>
   <simpara>
    Ist <link linkend="ini.post-max-size">post_max_size</link> zu klein
    eingestellt, können große Dateien nicht hochgeladen werden. Stellen Sie
    sicher, dass der Wert von <literal>post_max_size</literal> groß genug ist.
   </simpara>
   <simpara>
    Die Option
    <link linkend="ini.max-file-uploads">max_file_uploads</link> kontrolliert
    die maximale Anzahl der Dateien, die während einer Anfrage hochgeladen
    werden können. Wenn mehr Dateien hochgeladen werden als das Limit, werden
    diese nicht in das <varname>$_FILES</varname>-Array aufgenommen. Wenn
    <link linkend="ini.max-file-uploads">max_file_uploads</link>
    beispielsweise auf <literal>10</literal> gesetzt ist, so wird
    <varname>$_FILES</varname> nie mehr als 10 Einträge enthalten.
   </simpara>
   <simpara>
    Nicht zu prüfen, an welcher Datei Sie arbeiten, kann bedeuten, dass
    Benutzer auf sensible Informationen in anderen Verzeichnissen Zugriff
    erhalten.
   </simpara>
   <simpara>
    Aufgrund der vielen möglichen Arten der Darstellung von Verzeichnissen
    können wir nicht garantieren, dass Dateien mit exotischen Namen (wie &zb;
    mit enthaltenen Leerzeichen) auch wirklich richtig verarbeitet werden.
   </simpara>
   <simpara>
    Es ist nicht möglich, für normale Formularfelder und Dateifelder die
    gleiche Formularvariable (wie &zb; <literal>foo[]</literal>) zu verwenden.
   </simpara>
  </sect1>

  <sect1 xml:id="features.file-upload.multiple">
   <title>Upload mehrerer Dateien</title>
   <simpara>
    Mehrere Dateien können hochgeladen werden, indem Sie verschiedene Namen
    <literal>name</literal> für <literal>input</literal> verwenden.
   </simpara>
   <simpara>
    Es ist ebenfalls möglich, mehrere Dateien simultan hochzuladen, und die
    Informationen automatisch in Arrays zu erhalten. Um dies zu tun, verwenden
    Sie in dem HTML-Formular die gleiche Array-Sende-Syntax wie bei
    Auswahllisten mit Mehrfachauswahl und Checkboxen:
   </simpara>
   <para>
    <example>
     <title>Hochladen mehrerer Dateien</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>
   <simpara>
    Wenn das obige Formular übermittelt ist, werden die Arrays
    <varname>$_FILES['userfile']</varname>,
    <varname>$_FILES['userfile']['name']</varname> und
    <varname>$_FILES['userfile']['size']</varname> initialisiert.
   </simpara>
   <simpara>
    Nehmen wir zum Beispiel an, dass die Dateinamen
    <filename>/home/test/review.html</filename> und
    <filename>/home/test/xwp.out</filename> übermittelt wurden. In diesem Fall
    würde <varname>$_FILES['userfile']['name'][0]</varname>
    <filename>review.html</filename> enthalten und
    <varname>$_FILES['userfile']['name'][1]</varname> hätte den Wert
    <filename>xwp.out</filename>. Genauso würde
    <varname>$_FILES['userfile']['size'][0]</varname> die Dateigröße von
    <filename>review.html</filename> enthalten, usw.
   </simpara>
   <simpara>
    <varname>$_FILES['userfile']['name'][0]</varname>,
    <varname>$_FILES['userfile']['tmp_name'][0]</varname>,
    <varname>$_FILES['userfile']['size'][0]</varname> und
    <varname>$_FILES['userfile']['type'][0]</varname> sind ebenfalls gesetzt.
   </simpara>
   <warning>
    <simpara>
     Die Option
     <link linkend="ini.max-file-uploads">max_file_uploads</link> setzt ein
     Limit auf die Anzahl der Dateien, welche in einer Anfrage hochgeladen
     werden können. Sie müssen sicherstellen, dass ihr Formular nicht erlaubt,
     mehr Dateien hochzuladen als dieses Limit.
    </simpara>
   </warning>
   <para>
    <example>
     <title>Hochladen eines kompletten Verzeichnisses</title>
     <simpara>
      In den HTML-Feldern zum Hochladen von Dateien ist es mit dem Attribut
      <literal>webkitdirectory</literal> möglich, ein ganzes Verzeichnis
      hochzuladen. Diese Funktion wird von den meisten modernen Browsern
      unterstützt.
     </simpara>
     <simpara>
      Mit der Angabe <literal>full_path</literal> ist es möglich, die
      relativen Pfade zu speichern, oder das gleiche Verzeichnis auf dem
      Server zu rekonstruieren.
     </simpara>
     <programlisting role="html">
<![CDATA[
<form action="file-upload.php" method="post" enctype="multipart/form-data">
  Dieses Verzeichnis hochladen:<br />
  <input name="userfile[]" type="file" webkitdirectory multiple />
  <input type="submit" value="Dateien abschicken" />
</form>
]]>
     </programlisting>
    </example>

    <warning>
     <simpara>
      Das Attribut <literal>webkitdirectory</literal> ist nicht standardisiert
      und gehört nicht zu den Standards. Es sollte nicht auf Websites
      verwendet werden, die mit dem Internet verbunden sind: Es wird nicht bei
      jedem Benutzer funktionieren. Außerdem kann es große Inkompatibilitäten
      zwischen Implementierungen geben, und das Verhalten kann sich in Zukunft
      ändern.
     </simpara>
     <simpara>
      PHP analysiert nur die relativen Pfadinformationen, die vom
      Browser/User-Agenten übermittelt werden, und übergibt diese
      Informationen an das Array <varname>$_FILES</varname>. Es gibt keine
      Garantie, dass die Werte im Array <literal>full_path</literal> eine
      echte Verzeichnisstruktur enthalten, weshalb die PHP-Anwendung diesen
      Informationen nicht vertrauen darf.
     </simpara>
    </warning>
   </para>
  </sect1>

  <sect1 xml:id="features.file-upload.put-method">
   <title>PUT-Unterstützung</title>
   <para>
    PHP unterstützt die HTTP-PUT-Methode, welche von einigen Clients verwendet
    wird, um Dateien auf dem Server zu speichern. PUT-Anfragen sind weitaus
    unkomplizierter als ein POST-Dateiupload und sehen etwa so aus:
    <informalexample>
     <programlisting role="HTTP">
<![CDATA[
PUT /path/filename.html HTTP/1.1
]]>
     </programlisting>
    </informalexample>
   </para>
   <para>
    Das würde normalerweise bedeuten, dass der Client den nachfolgenden Inhalt
    als <filename>/path/filename.html</filename> auf dem Server speichern
    will. Natürlich ist es keine gute Idee, dass PHP oder Apache jeden
    Benutzer beliebige Dateien überschreiben lässt. Um eine solche Anfrage
    bearbeiten zu können, muss der Webserver erst angewiesen werden, ein
    bestimmtes PHP-Skript für die Abarbeitung aufzurufen. In Apache wird dies
    durch die Direktive <emphasis>Script</emphasis> festgelegt. Sie kann fast
    überall in der Apache-Konfigurationsdatei platziert werden, gebräuchlich
    ist die Platzierung innerhalb eines <literal>&lt;Directory&gt;</literal>-
    oder <literal>Virtualhost</literal>-Abschnitts. Eine Zeile wie die
    folgende erledigt dies:
    <informalexample>
     <programlisting>
<![CDATA[
Script PUT /put.php
]]>
     </programlisting>
    </informalexample>
   </para>
   <simpara>
    Diese Zeile legt fest, dass Apache alle PUT-Anfragen für URIs, die dem
    Kontext entsprechen, in dem diese Zeile steht, an das
    <filename>put.php</filename> Skript weiterleitet. Dies setzt natürlich
    voraus, dass PHP aktiv und für die
    <filename class="extension">.php</filename>-Dateierweiterung registriert
    ist.
   </simpara>
   <simpara>
    In der put.php könnte anschließend ein Code wie der folgende verwendet
    werden. Dieser würde den Inhalt der hochgeladenen Datei in die Datei
    <filename>myputfile.ext</filename> auf dem Server kopieren.
   </simpara>
   <para>
    <example>
     <title>Speichern von HTTP-PUT-Dateien</title>
     <programlisting role="php">
<![CDATA[
<?php
/* PUT Daten kommen in den stdin Stream */
$putdata = fopen("php://input","r");

/* Eine Datei zum Schreiben öffnen */
$fp = fopen("myputfile.ext","w");

/* Jeweils 1kB Daten lesen und
   in die Datei schreiben */
while ($data = fread($putdata,1024))
  fwrite($fp,$data);

/* Die Streams schließen */
fclose($fp);
fclose($putdata);
?>
]]>
     </programlisting>
    </example>
   </para>
  </sect1>

  <sect1 xml:id="features.file-upload.errors.seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
     <member><link linkend="security.filesystem">Dateisystem-Sicherheit</link></member>
    </simplelist>
   </para>
  </sect1>

 </chapter>

<!-- 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
-->