mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-18 18:08:54 +00:00
343 lines
8.6 KiB
XML
343 lines
8.6 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<sect1 xml:id="language.oop5.interfaces" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>Object Interfaces</title>
|
|
<para>
|
|
Object interfaces allow you to create code which specifies which methods a
|
|
class must implement, without having to define how these methods are
|
|
implemented. Interfaces share a namespace with classes and traits, so they may
|
|
not use the same name.
|
|
</para>
|
|
<para>
|
|
Interfaces are defined in the same way as a class, but with the <literal>interface</literal>
|
|
keyword replacing the <literal>class</literal> keyword and without any of the methods having
|
|
their contents defined.
|
|
</para>
|
|
<para>
|
|
All methods declared in an interface must be public; this is the nature of an
|
|
interface.
|
|
</para>
|
|
<para>
|
|
In practice, interfaces serve two complementary purposes:
|
|
</para>
|
|
<simplelist>
|
|
<member>
|
|
To allow developers to create objects of different classes that may be used interchangeably
|
|
because they implement the same interface or interfaces. A common example is multiple database access services,
|
|
multiple payment gateways, or different caching strategies. Different implementations may
|
|
be swapped out without requiring any changes to the code that uses them.
|
|
</member>
|
|
<member>
|
|
To allow a function or method to accept and operate on a parameter that conforms to an
|
|
interface, while not caring what else the object may do or how it is implemented. These interfaces
|
|
are often named like <literal>Iterable</literal>, <literal>Cacheable</literal>, <literal>Renderable</literal>,
|
|
or so on to describe the significance of the behavior.
|
|
</member>
|
|
</simplelist>
|
|
<para>
|
|
Interfaces may define
|
|
<link linkend="language.oop5.magic">magic methods</link> to require implementing classes to
|
|
implement those methods.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Although they are supported, including <link linkend="language.oop5.decon.constructor">constructors</link>
|
|
in interfaces is strongly discouraged. Doing so significantly reduces the flexibility of the object implementing the
|
|
interface. Additionally, constructors are not enforced by inheritance rules, which can cause inconsistent
|
|
and unexpected behavior.
|
|
</para>
|
|
</note>
|
|
|
|
<sect2 xml:id="language.oop5.interfaces.implements">
|
|
<title><literal>implements</literal></title>
|
|
<para>
|
|
To implement an interface, the <literal>implements</literal> operator is used.
|
|
All methods in the interface must be implemented within a class; failure to do
|
|
so will result in a fatal error. Classes may implement more than one interface
|
|
if desired by separating each interface with a comma.
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
A class can implement two interfaces which define a method with the
|
|
same name, only if the method declaration in both interfaces is identical.
|
|
</para>
|
|
</warning>
|
|
<warning>
|
|
<para>
|
|
A class that implements an interface may use a different name for its parameters than
|
|
the interface. However, as of PHP 8.0 the language supports <link linkend="functions.named-arguments">named arguments</link>, which means
|
|
callers may rely on the parameter name in the interface. For that reason, it is strongly
|
|
recommended that developers use the same parameter names as the interface being implemented.
|
|
</para>
|
|
</warning>
|
|
<note>
|
|
<para>
|
|
Interfaces can be extended like classes using the <link linkend="language.oop5.inheritance">extends</link>
|
|
operator.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
The class implementing the interface must declare all methods in the interface
|
|
with a <link linkend="language.oop.lsp">compatible signature</link>.
|
|
</para>
|
|
</note>
|
|
</sect2>
|
|
<!-- Move this to OOP constants page? -->
|
|
<sect2 xml:id="language.oop5.interfaces.constants">
|
|
<title><literal>Constants</literal></title>
|
|
<para>
|
|
It's possible for interfaces to have constants. Interface constants work exactly
|
|
like <link linkend="language.oop5.constants">class constants</link> except
|
|
they cannot be overridden by a class/interface that inherits them.
|
|
</para>
|
|
</sect2>
|
|
<sect2 xml:id="language.oop5.interfaces.examples">
|
|
&reftitle.examples;
|
|
<example xml:id="language.oop5.interfaces.examples.ex1">
|
|
<title>Interface example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
// Declare the interface 'Template'
|
|
interface Template
|
|
{
|
|
public function setVariable($name, $var);
|
|
public function getHtml($template);
|
|
}
|
|
|
|
// Implement the interface
|
|
// This will work
|
|
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;
|
|
}
|
|
}
|
|
|
|
// This will not work
|
|
// 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>Extendable Interfaces</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
interface A
|
|
{
|
|
public function foo();
|
|
}
|
|
|
|
interface B extends A
|
|
{
|
|
public function baz(Baz $baz);
|
|
}
|
|
|
|
// This will work
|
|
class C implements B
|
|
{
|
|
public function foo()
|
|
{
|
|
}
|
|
|
|
public function baz(Baz $baz)
|
|
{
|
|
}
|
|
}
|
|
|
|
// This will not work and result in a fatal error
|
|
class D implements B
|
|
{
|
|
public function foo()
|
|
{
|
|
}
|
|
|
|
public function baz(Foo $foo)
|
|
{
|
|
}
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<example xml:id="language.oop5.interfaces.examples.ex3">
|
|
<title>Multiple interface inheritance</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 with constants</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
interface A
|
|
{
|
|
const B = 'Interface constant';
|
|
}
|
|
|
|
// Prints: Interface constant
|
|
echo A::B;
|
|
|
|
|
|
// This will however not work because it's not allowed to
|
|
// override constants.
|
|
class B implements A
|
|
{
|
|
const B = 'Class constant';
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<example xml:id="language.oop5.interfaces.examples.ex5">
|
|
<title>Interfaces with abstract classes</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
interface A
|
|
{
|
|
public function foo(string $s): string;
|
|
|
|
public function bar(int $i): int;
|
|
}
|
|
|
|
// An abstract class may implement only a portion of an interface.
|
|
// Classes that extend the abstract class must implement the rest.
|
|
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>Extending and implementing simultaneously</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
|
|
class One
|
|
{
|
|
/* ... */
|
|
}
|
|
|
|
interface Usable
|
|
{
|
|
/* ... */
|
|
}
|
|
|
|
interface Updatable
|
|
{
|
|
/* ... */
|
|
}
|
|
|
|
// The keyword order here is important. 'extends' must come first.
|
|
class Two extends One implements Usable, Updatable
|
|
{
|
|
/* ... */
|
|
}
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
An interface, together with type declarations, provides a good way to make sure
|
|
that a particular object contains particular methods. See
|
|
<link linkend="language.operators.type">instanceof</link> operator and
|
|
<link linkend="language.types.declarations">type declarations</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
|
|
-->
|