interfaces.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 0c2a0d736df56dd0f3a1b88bd6ce7c975c38285a Maintainer: hholzgra Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: cc0198aafd5e2574511b539da241657c68738007 Reviewer: samesch -->
 <sect1 xml:id="language.oop5.interfaces" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Objekt-Interfaces (Schnittstellen)</title>
  <para>
   Objekt-Interfaces ermöglichen die Erzeugung von Code, der spezifiziert,
   welche Methoden und Eigenschaften eine Klasse implementieren muss, ohne
   definieren zu müssen, wie diese Methoden und Eigenschaften implementiert
   werden. Interfaces teilen sich einen Namensraum mit Klassen, Traits und
   Aufzählungen (Enums), daher dürfen sie nicht denselben Namen verwenden.
  </para>
  <para>
   Interfaces werden auf dieselbe Weise wie eine Klasse definiert, aber mit
   dem Schlüsselwort <literal>interface</literal> anstatt des Schlüsselworts
   <literal>class</literal>, und ohne, dass eine der Methoden ihren Inhalt
   definiert.
  </para>
  <para>
   Alle in einem Interface deklarierten Methoden müssen public sein; dies
   liegt in der Natur eines Interfaces.
  </para>
  <para>
   In der Praxis erfüllen die Interfaces zwei sich ergänzende Zwecke:
  </para>
  <simplelist>
   <member>
    Um Entwicklern zu ermöglichen, Objekte verschiedener Klassen zu erstellen,
    die austauschbar verwendet werden können, weil sie das gleiche Interface
    oder die gleichen Interfaces implementieren. Ein häufiges Beispiel sind
    mehrere Dienste für den Datenbankzugriff, mehrere Zahlungs-Gateways oder
    unterschiedliche Caching-Strategien. Verschiedene Implementierungen können
    ausgetauscht werden, ohne dass Änderungen am Code vorgenommen werden
    müssen, der sie verwendet.
   </member>
   <member>
    Um einer Funktion oder Methode zu ermöglichen, einen Parameter zu
    akzeptieren und zu bearbeiten, der der mit einem Interface konform ist,
    ohne sich darum zu kümmern, was das Objekt sonst noch tun kann oder wie es
    implementiert ist. Diese Interfaces werden oft benannt als
    <literal>Iterable</literal>, <literal>Cacheable</literal>,
    <literal>Renderable</literal>, oder so weiter, um die Bedeutung des des
    Verhaltens zu beschreiben.
   </member>
  </simplelist>
  <para>
   Interfaces können
   <link linkend="language.oop5.magic">magische Methoden</link> definieren, um
   implementierende Klassen zu zwingen, diese Methoden zu implementieren.
  </para>
  <note>
   <para>
    Obwohl diese unterstützt werden, wird von der Aufnahme von
    <link linkend="language.oop5.decon.constructor">Konstruktoren</link> in
    Interfaces dringend abgeraten. Dadurch wird die Flexibilität der Objekte,
    die das Interface implementieren, drastisch eingeschränkt. Außerdem werden
    Konstruktoren nicht durch Vererbungsregeln erzwungen, was zu
    Inkonsistenzen und unerwartetem Verhalten führen kann.
   </para>
  </note>

  <sect2 xml:id="language.oop5.interfaces.implements">
   <title><literal>implements</literal></title>
   <para>
    Um ein Interface zu implementieren, wird der Operator
    <literal>implements</literal> benutzt. Alle Methoden des Interfaces müssen
    innerhalb der Klasse implementiert werden, andernfalls führt dies zu einem
    schwerwiegenden Fehler. Klassen dürfen, falls dies gewünscht wird, mehr
    als ein Interface implementieren, indem man die Interfaces mit einem Komma
    voneinander trennt.
   </para>
   <warning>
    <para>
     Eine Klasse, die ein Interface implementiert, kann für ihre Parameter
     einen anderen Namen verwenden als das Interface. Seit PHP 8.0 unterstützt
     die Sprache
     <link linkend="functions.named-arguments">benannte Argumente</link>, was
     bedeutet, dass sich der Aufrufende auf den Parameternamen im Interface
     verlassen kann. Aus diesem Grund wird dringend empfohlen, dass Entwickler
     die gleichen Parameternamen verwenden wie das zu implementierende
     Interface.
    </para>
   </warning>
   <note>
    <para>
     Eine Schnittstelle kann ebenso wie eine Klasse mit Hilfe des Operators
     <link linkend="language.oop5.inheritance">extends</link> erweitert werden.
    </para>
   </note>
   <note>
    <para>
     Die Klasse, die die Schnittstelle implementiert, muss alle Methoden der
     Schnittstelle mit einer
     <link linkend="language.oop.lsp">kompatiblen Signatur</link> deklarieren.
     Eine Klasse kann mehrere Schnittstellen implementieren, die eine Methode
     mit demselben Namen deklarieren. In diesem Fall muss die Implementierung
     die <link linkend="language.oop.lsp">Regeln für die Signaturkompatibilität</link>
     für alle Schnittstellen befolgen. Auf diese Weise können
     <link linkend="language.oop5.variance">Kovarianz und Kontravarianz</link>
     angewendet werden.
    </para>
   </note>
  </sect2>
 <!-- Move this to OOP constants page? -->
  <sect2 xml:id="language.oop5.interfaces.constants">
   <title>Konstanten</title>
   <para>
    Eine Schnittstelle kann Konstanten definieren. Schnittstellen-Konstanten
    funktionieren genauso wie
    <link linkend="language.oop5.constants">Klassenkonstanten</link>. Vor
    PHP 8.1.0 können sie nicht von einer Klasse/Schnittstelle überschrieben
    werden, die sie erbt.
   </para>
  </sect2>
  <sect2 xml:id="language.oop5.interfaces.properties">
   <title>Eigenschaften</title>
   <simpara>
    Seit PHP 8.4.0 können Schnittstellen auch Eigenschaften deklarieren.
    In diesem Fall muss die Deklaration angeben, ob die Eigenschaft lesbar,
    schreibbar oder beides sein soll.
    Die Deklaration der Schnittstelle gilt nur für den öffentlichen Lese- und
    Schreibzugriff.
   </simpara>
   <simpara>
    Eine Klasse kann eine Schnittstelleneigenschaft auf mehrere Arten erfüllen.
    Sie kann eine öffentliche Eigenschaft definieren.
    Sie kann eine öffentliche
    <link linkend="language.oop5.property-hooks.virtual">virtuelle Eigenschaft</link>
    definieren, die nur den entsprechenden Hook implementiert.
    Oder eine lesbare Eigenschaft kann durch eine
    <literal>readonly</literal>-Eigenschaft erfüllt werden.
    Eine Schnittstelleneigenschaft, die gesetzt werden kann, kann jedoch nicht
    <literal>readonly</literal> sein.
   </simpara>
   <example>
    <title>Beispiel für Schnittstelleneigenschaften</title>
    <programlisting role="php">
<![CDATA[
<?php
interface I
{
    // Eine implementierende Klasse MUSS eine öffentlich lesbare Eigenschaft
    // haben, wobei es keine Rolle spielt, ob sie öffentlich gesetzt werden kann.
    public string $readable { get; }

    // Eine implementierende Klasse MUSS eine öffentlich schreibbare Eigenschaft
    // haben, wobei es keine Rolle spielt, ob sie öffentlich lesbar ist oder nicht.
    public string $writeable { set; }

    // Eine implementierende Klasse MUSS eine Eigenschaft haben, die sowohl
    // öffentlich lesbar als auch öffentlich schreibbar ist.
    public string $both { get; set; }
}

// Diese Klasse implementiert alle drei Eigenschaften als konventionelle, nicht
// eingehängte Eigenschaften. Dies ist absolut gültig.
class C1 implements I
{
    public string $readable;

    public string $writeable;

    public string $both;
}

// Diese Klasse implementiert alle drei Eigenschaften, indem sie nur die
// angeforderten Hooks verwendet. Dies ist auch absolut gültig.
class C2 implements I
{
    private string $written = '';
    private string $all = '';

    // Verwendet nur einen get-Hook, um eine virtuelle Eigenschaft zu erstellen.
    // Damit wird die Anforderung "public get" erfüllt.
    // Sie ist nicht schreibbar, aber das ist für die Schnittstelle nicht
    // erforderlich.
    public string $readable { get => strtoupper($this->writeable); }

    // Die Schnittstelle verlangt nur, dass die Eigenschaft gesetzt werden
    // kann, aber auch get-Operationen sind absolut zulässig.
    // Dieses Beispiel erzeugt eine virtuelle Eigenschaft, was in Ordnung ist.
    public string $writeable {
        get => $this->written;
        set {
            $this->written = $value;
        }
    }

    // Diese Eigenschaft verlangt, dass sowohl Lesen als auch Schreiben
    // möglich ist, sodass entweder beides implementiert werden muss
    // oder das Standardverhalten beibehalten werden kann.
    public string $both {
        get => $this->all;
        set {
            $this->all = strtoupper($value);
        }
    }
}
?>
]]>
    </programlisting>
   </example>
  </sect2>
  <sect2 xml:id="language.oop5.interfaces.examples">
   &reftitle.examples;
   <example xml:id="language.oop5.interfaces.examples.ex1">
    <title>Interface-Beispiel</title>
     <programlisting role="php">
<![CDATA[
<?php
// Deklariere das Interface 'Template'
interface Template
{
    public function setVariable($name, $var);
    public function getHtml($template);
}

// Implementiere das Interface
// Dies funktioniert
class WorkingTemplate implements Template
{
    private $vars = [];

    public function setVariable($name, $var)
    {
        $this->vars[$name] = $var;
    }

    public function getHtml($template)
    {
        foreach($this->vars as $name => $value) {
            $template = str_replace('{' . $name . '}', $value, $template);
        }

        return $template;
    }
}

// Dies wird nicht funktionieren
// Fatal error: Class BadTemplate contains 1 abstract methods
// and must therefore be declared abstract (Template::getHtml)
class BadTemplate implements Template
{
    private $vars = [];

    public function setVariable($name, $var)
    {
        $this->vars[$name] = $var;
    }
}
?>
]]>
    </programlisting>
   </example>
   <example xml:id="language.oop5.interfaces.examples.ex2">
    <title>Erweiterbare Interfaces</title>
    <programlisting role="php">
<![CDATA[
<?php
interface A
{
    public function foo();
}

interface B extends A
{
    public function baz(Baz $baz);
}

// Dies Funktioniert
class C implements B
{
    public function foo()
    {
    }

    public function baz(Baz $baz)
    {
    }
}

// Dies funktioniert nicht und führt zu einem schwerwiegenden Fehler
class D implements B
{
    public function foo()
    {
    }

    public function baz(Foo $foo)
    {
    }
}
?>
]]>
     </programlisting>
   </example>
   <example xml:id="language.oop5.interfaces.examples.variance.multiple.interfaces">
    <title>Varianzkompatibilität mit mehreren Schnittstellen</title>
     <programlisting role="php">
<![CDATA[
<?php
class Foo {}
class Bar extends Foo {}

interface A {
    public function myfunc(Foo $arg): Foo;
}

interface B {
    public function myfunc(Bar $arg): Bar;
}

class MyClass implements A, B
{
    public function myfunc(Foo $arg): Bar
    {
        return new Bar();
    }
}
?>
]]>
     </programlisting>
   </example>
   <example xml:id="language.oop5.interfaces.examples.ex3">
    <title>Interface-Mehrfachvererbung</title>
     <programlisting role="php">
<![CDATA[
<?php
interface A
{
    public function foo();
}

interface B
{
    public function bar();
}

interface C extends A, B
{
    public function baz();
}

class D implements C
{
    public function foo()
    {
    }

    public function bar()
    {
    }

    public function baz()
    {
    }
}
?>
]]>
    </programlisting>
   </example>
   <example xml:id="language.oop5.interfaces.examples.ex4">
    <title>Interfaces mit Konstanten</title>
     <programlisting role="php">
<![CDATA[
<?php
interface A
{
    const B = 'Interface-Konstante';
}

// Ausgabe: Interface-Konstante
echo A::B;

class B implements A
{
    const B = 'Klassen-Konstante';
}

// Ausgabe: Klassen-Konstante
// Vor PHP 8.1.0 funktioniert dies allerdings nicht, da es nicht erlaubt
// war, Konstanten zu überschreiben.
echo B::B;
?>
]]>
    </programlisting>
   </example>
   <example xml:id="language.oop5.interfaces.examples.ex5">
    <title>Interfaces mit abstrakten Klassen</title>
    <programlisting role="php">
<![CDATA[
<?php
interface A
{
    public function foo(string $s): string;

    public function bar(int $i): int;
}

// Eine abstrakte Klasse muss ein Interface nicht komplett implementieren.
// Klassen, die die abstrakte Klasse erweitern, müssen den Rest implementieren.
abstract class B implements A
{
    public function foo(string $s): string
    {
        return $s . PHP_EOL;
    }
}

class C extends B
{
    public function bar(int $i): int
    {
        return $i * 2;
    }
}
?>
]]>
    </programlisting>
   </example>
   <example xml:id="language.oop5.interfaces.examples.ex6">
    <title>Gleichzeitiges Erweitern und Implementieren</title>
    <programlisting role="php">
<![CDATA[
<?php

class One
{
    /* ... */
}

interface Usable
{
    /* ... */
}

interface Updatable
{
    /* ... */
}

// Die Reihenfolge der Schlüsselwörter ist hier wichtig. 'extends' muss an
// erster Stelle stehen.
class Two extends One implements Usable, Updatable
{
    /* ... */
}
?>
]]>
    </programlisting>
   </example>
   <para>
    Ein Interface bietet in Verbindung mit Typ-Deklarationen eine gute
    Möglichkeit, um sicherzustellen, dass ein bestimmtes Objekt bestimmte
    Methoden enthält. Siehe
    <link linkend="language.operators.type">instanceof</link>-Operator und
    <link linkend="language.types.declarations">Typdeklarationen</link>.
   </para>
  </sect2>

 </sect1>

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