archived-doc-de/language/wrappers/php.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: f56de7ebe7a1a85ce9e44a2bf6b77b07adfe3ae4 Maintainer: samesch Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="wrappers.php" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" annotations="verify_info:false" role="stream_wrapper">
 <refnamediv>
  <refname>php://</refname>
  <refpurpose>Zugriff auf verschiedene I/O-Streams</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <para>
   PHP stellt eine Reihe verschiedener I/O-Streams zur Verfügung. Diese
   ermöglichen den Zugriff auf PHP-eigene Ein- und Ausgabestreams,
   Dateideskriptoren für Standardeingabe, -ausgabe und -fehler, temporäre
   Dateistreams im Speicher und auf der Festplatte sowie Filter, die andere
   Dateiressourcen während des Lesen und Schreibens manipulieren können.
  </para>

  <refsect2 xml:id="wrappers.php.std">
   <title>php://stdin, php://stdout und php://stderr</title>
   <simpara>
    <filename>php://stdin</filename>, <filename>php://stdout</filename> und
    <filename>php://stderr</filename> ermöglichen den direkten Zugriff auf den
    entsprechenden Ein- oder Ausgabestream des PHP-Prozesses. Der Stream
    verweist auf eine Kopie eines Dateideskriptors, &dh; wenn
    <filename>php://stdin</filename> geöffnet und später wieder geschlossen
    wird, wird nur die Kopie des Deskriptors geschlossen - der eigentliche
    Stream, auf den <constant>STDIN</constant> verweist, bleibt davon
    unberührt. Es wird empfohlen, einfach die Konstanten
    <constant>STDIN</constant>, <constant>STDOUT</constant> und
    <constant>STDERR</constant> zu verwenden, anstatt die Streams manuell mit
    diesen Wrappern zu öffnen.
   </simpara>
   <simpara>
    <filename>php://stdin</filename> ist schreibgeschützt, während
    <filename>php://stdout</filename> und <filename>php://stderr</filename>
    nur geschrieben werden können.
   </simpara>
  </refsect2>

  <refsect2 xml:id="wrappers.php.input">
   <title>php://input</title>
   <simpara>
    <filename>php://input</filename> ist ein schreibgeschützter Stream, mit dem
    Rohdaten aus dem Body der Anfrage gelesen werden können. Wenn die Option
    <link linkend="ini.enable-post-data-reading">enable_post_data_reading</link>
    aktiviert ist,  steht<filename>php://input</filename> in POST-Anfragen mit
    <literal>enctype="multipart/form-data"</literal> nicht zur Verfügung.
   </simpara>
  </refsect2>

  <refsect2 xml:id="wrappers.php.output">
   <title>php://output</title>
   <para>
    <filename>php://output</filename> ist ein nur schreibbarer Stream, mit dem
    auf die gleiche Weise in den Ausgabepuffer geschrieben werden kann wie mit
    <function>print</function> und <function>echo</function>.
   </para>
  </refsect2>

  <refsect2 xml:id="wrappers.php.fd">
   <title>php://fd</title>
   <simpara>
    Mit <filename>php://fd</filename> kann direkt auf den angegebenen
    Dateideskriptor zugegriffen werden; &zb; verweist
    <filename>php://fd/3</filename> auf den Dateideskriptor 3.
   </simpara>
  </refsect2>

  <refsect2 xml:id="wrappers.php.memory">
   <title>php://memory und php://temp</title>
   <simpara>
    <filename>php://memory</filename> und <filename>php://temp</filename> sind
    les- und schreibbare Streams, mit denen temporäre Daten in einem
    dateiähnlichen Wrapper gespeichert werden können. Ein Unterschied zwischen
    den beiden besteht darin, dass <filename>php://memory</filename> die Daten
    immer im Speicher ablegt, während <filename>php://temp</filename> eine
    temporäre Datei verwendet, sobald die Menge der gespeicherten Daten eine
    vordefinierte Grenze (der Standardwert ist 2 MB) erreicht. Der Speicherort
    dieser temporären Datei wird auf die gleiche Weise ermittelt, wie bei der
    Funktion <function>sys_get_temp_dir</function>.
   </simpara>
   <simpara>
    Das Speicherlimit von <filename>php://temp</filename> kann durch Anhängen
    von <literal>/maxmemory:NN</literal> festgelegt werden, wobei
    <literal>NNN</literal> die maximale Datenmenge in Bytes ist, die im
    Speicher gehalten werden soll, bevor eine temporäre Datei verwendet wird.
   </simpara>
   <caution>
    <simpara>
     Manche PHP-Erweiterungen benötigen einen Standard-IO-Stream und versuchen,
     einen gegebenen Stream in einen Standard-IO-Stream umzuwandeln. Diese
     Umwandlung kann bei Speicher-Streams fehlschlagen, da hierfür die
     C-Funktion <function>fopencookie</function> verfügbar sein muss. Unter
     Windows steht diese C-Funktion <emphasis>nicht</emphasis> zur Verfügung.
    </simpara>
   </caution>
  </refsect2>

  <refsect2 xml:id="wrappers.php.filter">
   <title>php://filter</title>
   <simpara>
    <filename>php://filter</filename> ist eine Art Meta-Wrapper, mit dem
    <link linkend="filters">Filter</link> auf einen Stream angewendet werden
    können, wenn dieser geöffnet wird. Dies ist nützlich bei
    All-in-One-Dateifunktionen wie <function>readfile</function>,
    <function>file</function> und <function>file_get_contents</function>, wo
    es sonst keine Möglichkeit gibt, einen Filter auf den Stream anzuwenden,
    bevor der Inhalt gelesen wird.
   </simpara>
   <para>
    Der Wrapper <filename>php://filter</filename> akzeptiert die folgenden
    Parameter als Teil seines Pfades. Es können mehrere Filterketten in einem
    Pfad angegeben werden. Einzelheiten zur Verwendung dieser Parameter werden
    in den Beispielen erläutert.
   </para>
   <para>
    <table>
     <title>Parameter für php://filter</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Name</entry>
        <entry>&Description;</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>
         <literal>resource=&lt;zu filternder Stream&gt;</literal>
        </entry>
        <entry>
         Dieser Parameter ist erforderlich; er gibt den Stream an, der
         gefiltert werden soll.
        </entry>
       </row>
       <row>
        <entry>
         <literal>read=&lt;Liste der Filter, die auf den Lese-Stream angewendet werden sollen&gt;</literal>
        </entry>
        <entry>
         Dieser Parameter ist optional; ein oder mehrere Filternamen, getrennt
         durch ein Pipe-Zeichen (<literal>|</literal>).
        </entry>
       </row>
       <row>
        <entry>
         <literal>write=&lt;Liste der Filter, die auf den Schreib-Stream angewendet werden sollen&gt;</literal>
        </entry>
        <entry>
         Dieser Parameter ist optional; ein oder mehrere Filternamen, getrennt
         durch ein Pipe-Zeichen (<literal>|</literal>).
        </entry>
       </row>
       <row>
        <entry>
         <literal>&lt;Liste der Filter, die auf beide Streams angewendet werden sollen&gt;</literal>
        </entry>
        <entry>
         Alle Filterlisten, denen kein <literal>read=</literal> oder
         <literal>write=</literal> vorangestellt ist, werden je nach Bedarf
         sowohl auf den Lese- als auch auf den Schreib-Stream angewendet.
        </entry>
       </row>
      </tbody>
     </tgroup>
    </table>
   </para>
  </refsect2>
 </refsect1>

 <refsect1 role="options"><!-- {{{ -->
  &reftitle.options;
  <para>
   <table>
    <title>
     Zusammenfassung des Wrappers (für <literal>php://filter</literal> siehe
     die Zusammenfassung des Wrappers, der gefiltert wird)
    </title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Eigenschaft</entry>
       <entry>wird unterstützt</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>Eingeschränkt durch <link linkend="ini.allow-url-fopen">allow_url_fopen</link></entry>
       <entry>Nein</entry>
      </row>
      <row>
       <entry>Eingeschränkt durch <link linkend="ini.allow-url-include">allow_url_include</link></entry>
       <entry>
        Nur <literal>php://input</literal>,
        <literal>php://stdin</literal>,
        <literal>php://memory</literal> und
        <literal>php://temp</literal>.
       </entry>
      </row>
      <row>
       <entry>Erlaubt Lesen</entry>
       <entry>
        Nur <literal>php://stdin</literal>,
        <literal>php://input</literal>,
        <literal>php://fd</literal>,
        <literal>php://memory</literal> und
        <literal>php://temp</literal>.
       </entry>
      </row>
      <row>
       <entry>Erlaubt Schreiben</entry>
       <entry>
        Nur <literal>php://stdout</literal>,
        <literal>php://stderr</literal>,
        <literal>php://output</literal>,
        <literal>php://fd</literal>,
        <literal>php://memory</literal> und
        <literal>php://temp</literal>.
       </entry>
      </row>
      <row>
       <entry>Erlaubt Anfügen</entry>
       <entry>
        Nur <literal>php://stdout</literal>,
        <literal>php://stderr</literal>,
        <literal>php://output</literal>,
        <literal>php://fd</literal>,
        <literal>php://memory</literal> und
        <literal>php://temp</literal> (Entspricht dem Schreiben).
       </entry>
      </row>
      <row>
       <entry>Erlaubt gleichzeitiges Lesen und Schreiben</entry>
       <entry>
        Nur <literal>php://fd</literal>,
        <literal>php://memory</literal> und
        <literal>php://temp</literal>.
       </entry>
      </row>
      <row>
       <entry>Unterstützt <function>stat</function></entry>
       <entry>
        Nein, aber <literal>php://memory</literal> und
        <literal>php://temp</literal> unterstützen <function>fstat</function>.
       </entry>
      </row>
      <row>
       <entry>Unterstützt <function>unlink</function></entry>
       <entry>Nein</entry>
      </row>
      <row>
       <entry>Unterstützt <function>rename</function></entry>
       <entry>Nein</entry>
      </row>
      <row>
       <entry>Unterstützt <function>mkdir</function></entry>
       <entry>Nein</entry>
      </row>
      <row>
       <entry>Unterstützt <function>rmdir</function></entry>
       <entry>Nein</entry>
      </row>
      <row>
       <entry>Unterstützt <function>stream_select</function></entry>
       <entry>
        Nur <literal>php://stdin</literal>,
        <literal>php://stdout</literal>,
        <literal>php://stderr</literal>,
        <literal>php://fd</literal> und
        <literal>php://temp</literal>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </refsect1> <!-- }}} -->

 <refsect1 role="examples"><!-- {{{ -->
  &reftitle.examples;
  <example><!-- {{{ -->
   <title>php://temp/maxmemory</title>
   <para>
    Mit diesem optionalen Parameter kann festgelegt werden, wie viel
    Speicherplatz <filename>php://temp</filename> verwenden darf, bevor eine
    temporäre Datei verwendet wird.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
// Das Limit auf 5 MB setzen.
$fiveMBs = 5 * 1024 * 1024;
$fp = fopen("php://temp/maxmemory:$fiveMBs", 'r+');

fputs($fp, "hello\n");

// Lesen, was geschrieben wurde.
rewind($fp);
echo stream_get_contents($fp);
?>
]]>
   </programlisting>
  </example><!-- }}} -->
  <example><!-- {{{ -->
   <title>php://filter/resource=&lt;zu filternder Stream&gt;</title>
   <para>
    Dieser Parameter muss sich am Ende der
    <filename>php://filter</filename>-Spezifikation befinden und auf den
    Stream verweisen, der gefiltert werden soll.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
/* Da keine Filter angegeben werden, entspricht dies einem einfachen
  readfile("http://www.example.com"); */

readfile("php://filter/resource=http://www.example.com");
?>
]]>
   </programlisting>
  </example><!-- }}} -->
  <example><!-- {{{ -->
   <title>php://filter/read=&lt;Liste der Filter, die auf den Lese-Stream angewendet werden sollen&gt;</title>
   <para>
    Dieser Parameter akzeptiert einen oder mehrere Filternamen, die durch das
    Pipe-Zeichen <literal>|</literal> getrennt sind.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
/* Dies gibt den Inhalt von www.example.com
  komplett in Großbuchstaben aus */
readfile("php://filter/read=string.toupper/resource=http://www.example.com");

/* Dies bewirkt dasselbe wie oben,
  aber zusätzlich wird ROT13-kodiert */
readfile("php://filter/read=string.toupper|string.rot13/resource=http://www.example.com");
?>
]]>
   </programlisting>
  </example><!-- }}} -->
  <example><!-- {{{ -->
   <title>php://filter/write=&lt;Liste der Filter, die auf den Schreib-Stream angewendet werden sollen&gt;</title>
   <para>
    Dieser Parameter akzeptiert einen oder mehrere Filternamen, die durch das
    Pipe-Zeichen <literal>|</literal> getrennt sind.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
/* Dies wendet einen rot13-Filter auf die Zeichenkette
  "Hello World" an und schreibt sie dann in die Datei
  example.txt im aktuellen Verzeichnis */
file_put_contents("php://filter/write=string.rot13/resource=example.txt","Hello World");
?>
]]>
   </programlisting>
  </example><!-- }}} -->
  <example>
   <title>php://memory und php://temp sind nicht wiederverwendbar</title>
   <para>
    <filename>php://memory</filename> und <filename>php://temp</filename>
    können nicht wiederverwendet werden, &dh; nachdem die Streams geschlossen
    wurden, kann nicht mehr auf sie zugegriffen werden.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
file_put_contents('php://memory', 'PHP');
echo file_get_contents('php://memory'); // gibt nichts aus
]]>
   </programlisting>
  </example>
  <example>
   <title>JSON-Daten mittels php://input aus dem Body einer Anfrage lesen</title>
   <para>
    Dieses Beispiel zeigt, wie mittels <filename>php://input</filename>
    JSON-Rohdaten aus POST-, PUT- und PATCH-Anfragen gelesen werden können.
   </para>
   <programlisting role="php">
<![CDATA[
<?php
$input = file_get_contents("php://input");
$json_array = json_decode(
  json: $input,
  associative: true,
  flags: JSON_THROW_ON_ERROR
);

echo "Empfangene JSON-Daten: ";
print_r($json_array);
?>
]]>
   </programlisting>
  </example>
 </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
-->