htmlspecialchars.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: eabde0419cf90f596f60db00e31fcb6ebe41ac55 Maintainer: sammywg Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: e4b52745bc8ef288726f8e76e7fdc6277a2f656f Reviewer: samesch -->
<refentry xml:id="function.htmlspecialchars" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>htmlspecialchars</refname>
  <refpurpose>Wandelt Sonderzeichen in HTML-Entities um</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>htmlspecialchars</methodname>
   <methodparam><type>string</type><parameter>string</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401</initializer></methodparam>
   <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>encoding</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>double_encode</parameter><initializer>&true;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Bestimmte Zeichen haben in HTML eine spezielle Bedeutung und sollten in
   HTML-Entities dargestellt werden, um ihre Bedeutung zu behalten. Diese
   Funktion gibt eine Zeichenkette zurück, in der diese Umwandlungen
   durchgeführt wurden. Ist es erforderlich, dass alle Teilzeichenketten der
   Eingabe, die zugeordnete benannte Entities haben, übersetzt werden, sollte
   stattdessen <function>htmlentities</function> verwendet werden.
  </para>
  <para>
   Wenn die Eingabezeichenkette, die dieser Funktion übergeben wird, und das
   endgültige Dokument den gleichen Zeichensatz haben, ist diese Funktion
   ausreichend, um Eingaben für die meisten Kontexte eines HTML-Dokuments
   vorzubereiten. Wenn allerdings die Eingabe Zeichen darstellen kann, die
   nicht im Zeichensatz des endgültigen Dokuments kodiert sind, und Sie
   diese Zeichen beibehalten wollen (als numerische oder benannte Entities),
   kann sowohl diese Funktion als auch <function>htmlentities</function> (die
   nur Teilzeichenketten, die benannte Entity-Entsprechungen haben, kodiert)
   ungenügend sein. Stattdessen muss u. U.
   <function>mb_encode_numericentity</function> verwendet werden.
  </para>
  <para>
   <table>
    <title>Durchgeführte Ersetzungen</title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>Zeichen</entry>
       <entry>Ersetzung</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>&amp;</literal> (Kaufmanns-Und)</entry>
       <entry><literal>&amp;amp;</literal></entry>
      </row>
      <row>
       <entry><literal>&quot;</literal> (doppeltes Anführungszeichen)</entry>
       <entry>
        <literal>&amp;quot;</literal>, falls <constant>ENT_NOQUOTES</constant>
        nicht gesetzt ist
       </entry>
      </row>
      <row>
       <entry><literal>'</literal> (einfaches Anführungszeichen)</entry>
       <entry>
        <literal>&amp;#039;</literal> (für <constant>ENT_HTML401</constant>)
        oder <literal>&amp;apos;</literal> (für
        <constant>ENT_XML1</constant>, <constant>ENT_XHTML</constant> oder
        <constant>ENT_HTML5</constant>), aber nur wenn
        <constant>ENT_QUOTES</constant> gesetzt ist
       </entry>
      </row>
      <row>
       <entry><literal>&lt;</literal> (kleiner als)</entry>
       <entry><literal>&amp;lt;</literal></entry>
      </row>
      <row>
       <entry><literal>&gt;</literal> (größer als)</entry>
       <entry><literal>&amp;gt;</literal></entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       Die zu umzuwandelnde Zeichenkette.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       Eine Bitmaske von einem oder mehreren der folgenden Flags, die die
       Behandlung von Anführungszeichen, ungültigen Zeichenketten und den
       genutzten Dokumententyp festlegen. Der Standardwert ist
       <literal>ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401</literal>.
       <table>
        <title>Verfügbare <parameter>flags</parameter>-Konstanten</title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Name der Konstante</entry>
           <entry>&Description;</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><constant>ENT_COMPAT</constant></entry>
           <entry>
            Wandelt nur doppelte Anführungszeichen um und lässt einfache
            Anführungszeichen unverändert.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_QUOTES</constant></entry>
           <entry>
            Wandelt sowohl doppelte als auch einfache Anführungszeichen um.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_NOQUOTES</constant></entry>
           <entry>
            Lässt doppelte und einfache Anführungszeichen unverändert.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_IGNORE</constant></entry>
           <entry>
            Verwirft ungültige Code-Unit-Sequenzen, anstatt eine leere
            Zeichenkette zurückzugeben. Die Nutzung dieser Option ist nicht
            empfehlenswert, da sie
            <link xlink:href="&url.delete.nonchars;">Auswirkungen auf die Sicherheit</link>
            haben kann.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_SUBSTITUTE</constant></entry>
           <entry>
            Ersetzt ungültige Code-Unit-Sequenzen mit dem
            Unicode-Ersatzzeichen U+FFFD (UTF-8) oder &amp;#xFFFD;
            (andernfalls), anstatt eine leere Zeichenkette zurückzugeben.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_DISALLOWED</constant></entry>
           <entry>
            Ersetzt Codepoints, welche in dem angegebenen Dokumenttyp ungültig
            sind, mit dem Unicode-Ersatzzeichen U+FFFD (UTF-8) oder
            &amp;#xFFFD; (andernfalls), anstatt sie zu belassen. Das kann zum
            Beispiel nützlich sein, um die Wohlgeformtheit von XML-Dokumenten
            mit eingebetteten externen Inhalten sicherzustellen.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_HTML401</constant></entry>
           <entry>
            Behandle Code als HTML 4.01.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_XML1</constant></entry>
           <entry>
            Behandle Code als XML 1.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_XHTML</constant></entry>
           <entry>
            Behandle Code als XHTML.
           </entry>
          </row>
          <row>
           <entry><constant>ENT_HTML5</constant></entry>
           <entry>
            Behandle Code als HTML 5.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>encoding</parameter></term>
     <listitem>
      &strings.parameter.encoding;
      <para>
       Für den Gebrauch dieser Funktion sind die Zeichenkodierungen
       <literal>ISO-8859-1</literal>, <literal>ISO-8859-15</literal>,
       <literal>UTF-8</literal>, <literal>cp866</literal>,
       <literal>cp1251</literal>, <literal>cp1252</literal> und
       <literal>KOI8-R</literal> tatsächlich äquivalent, vorausgesetzt,
       <parameter>string</parameter> selbst ist gültig in der
       Zeichenkodierung, da die von <function>htmlspecialchars</function>
       betroffenen Zeichen in allen genannten Zeichenkodierungen an gleicher
       Position stehen.
      </para>
      &reference.strings.charsets;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>double_encode</parameter></term>
     <listitem>
      <para>
       Wird der Parameter <parameter>double_encode</parameter> ausgeschaltet,
       kodiert PHP bereits existierende HTML-Entities nicht noch einmal.
       Standardmäßig werden jedoch alle Zeichen umgewandelt.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Die umgewandelte Zeichenkette.
  </para>
  <para>
   Enthält <parameter>string</parameter> eine in dem übergebenen
   <parameter>encoding</parameter> ungültige Code-Unit-Sequenz, wird eine
   leere Zeichenkette zurückgegeben, sofern weder das
   <constant>ENT_IGNORE</constant>- noch das
   <constant>ENT_SUBSITUTE</constant>-Flag gesetzt sind.
  </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.1.0</entry>
      <entry>
       <parameter>flags</parameter> geändert von
       <constant>ENT_COMPAT</constant> zu <constant>ENT_QUOTES</constant> |
       <constant>ENT_SUBSTITUTE</constant> | <constant>ENT_HTML401</constant>.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>htmlspecialchars</function>-Beispiel</title>
    <programlisting role="php">
<![CDATA[
<?php
$neu = htmlspecialchars("<a href='test'>Test</a>", ENT_QUOTES);
echo $neu; // &lt;a href=&#039;test&#039;&gt;Test&lt;/a&gt;
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Zu beachten ist, dass diese Funktion nur die o. a. Umwandlungen
    durchführt. Für eine vollständige Umwandlung in Entities siehe
    <function>htmlentities</function>.
   </para>
  </note>
  <note>
   <para>
    Im Fall von mehrdeutigen <parameter>flags</parameter>-Werten gelten die
    folgenden Regeln:
   </para>
   <para>
    <itemizedlist>
     <listitem>
      <simpara>
       Wird weder <constant>ENT_COMPAT</constant>,
       <constant>ENT_QUOTES</constant> oder <constant>ENT_NOQUOTES</constant>
       angegeben, ist der Standardwert <constant>ENT_NOQUOTES</constant>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Werden mehrere von <constant>ENT_COMPAT</constant>,
       <constant>ENT_QUOTES</constant> und <constant>ENT_NOQUOTES</constant>
       angegeben, erhält <constant>ENT_QUOTES</constant> den Vorrang, gefolgt
       von <constant>ENT_COMPAT</constant>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Wird weder <constant>ENT_HTML401</constant>,
       <constant>ENT_HTML5</constant>, <constant>ENT_XHTML</constant> noch
       <constant>ENT_XML1</constant> angegeben, ist der Standardwert
       <constant>ENT_HTML401</constant>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Werden mehrere von <constant>ENT_HTML401</constant>,
       <constant>ENT_HTML5</constant>, <constant>ENT_XHTML</constant> und
       <constant>ENT_XML1</constant> angegeben, erhält
       <constant>ENT_HTML5</constant> den Vorrang, gefolgt von
       <constant>ENT_XHTML</constant>, <constant>ENT_XML1</constant> und
       <constant>ENT_HTML401</constant>.
      </simpara>
     </listitem>
     <listitem>
      <simpara>
       Werden mehrere von <constant>ENT_DISALLOWED</constant>,
       <constant>ENT_IGNORE</constant> und <constant>ENT_SUBSTITUTE</constant>
       angegeben, erhält <constant>ENT_IGNORE</constant> den Vorrang, gefolgt
       von <constant>ENT_SUBSTITUTE</constant>.
      </simpara>
     </listitem>
    </itemizedlist>
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>get_html_translation_table</function></member>
    <member><function>htmlspecialchars_decode</function></member>
    <member><function>strip_tags</function></member>
    <member><function>htmlentities</function></member>
    <member><function>nl2br</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
-->