Skip to content

6. Interfaces

Uma interface é uma estrutura que define protótipos de métodos. Uma classe que implementa uma interface deve implementar o código de todos os métodos da interface. Uma interface é um contrato: ela especifica o que um objeto pode fazer, sem especificar como ele o faz.

6.1. A estrutura de diretórios dos scripts

Os scripts deste capítulo estão na pasta [scripts-console/interfaces]:

1
2
3
4
5
6
7
8
php8-oct-2026/scripts-console/interfaces
├── ICalculation.php
├── IExample.php
├── IExample2.php
├── interface-01.php
├── interface-02.php
├── interface-03.php
└── interface-04.php

6.2. Uma primeira interface

Definimos uma interface chamada [IExample] em um script chamado [IExample.php]. No mesmo script, definimos duas classes que implementam a interface [IExample]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// namespace
namespace Examples;

// uma interface
interface IExample
{
    // os métodos da interface
    public function add(int $i, int $j): int;

    public function subtract(int $i, int $j): int;
}

// implementação 1 da interface IExample
class Class1 implements IExample
{
    public function add(int $a, int $b): int
    {
        return $a + $b + 10;
    }

    public function subtract(int $a, int $b): int
    {
        return $a - $b + 20;
    }
}

// implementação 2 da interface IExample
class Class2 implements IExample
{
    public function add(int $a, int $b): int
    {
        return $a + $b + 100;
    }

    public function subtract(int $a, int $b): int
    {
        return $a - $b + 200;
    }
}

Comentários

  • Linhas 10–15: A interface [IExample] define dois métodos: a função [add] (linha 13) e a função [subtract] (linha 15). A interface não define o código desses métodos. As classes que implementam a interface o farão. Os métodos de uma interface devem ser públicos;
  • linha 19: a classe [Class1] implementa ([implements]) a interface [IExample]. Ela define, portanto, o código dos métodos [add] (linha 21) e [subtract] (linha 26). Os nomes dos parâmetros podem diferir dos da interface ([$a] em vez de [$i]), mas seus tipos devem ser compatíveis. Observe, porém: com os argumentos nomeados do PHP 8, uma chamada a [add(i: 1, j: 2)] não funcionaria com [Class1]. É preferível, portanto, manter os nomes da interface;
  • Linhas 33–44: O mesmo vale para a classe [Class2].

Usamos a interface [IExample] no seguinte script [interface-01.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// inclusão e declaração das classes e interfaces usadas pelo script
require_once __DIR__ . "/IExample.php";
use Examples\Class1;
use Examples\Class2;
use Examples\IExample;

// função
function calculate(int $a, int $b, IExample $interface): void
{
    print $interface->add($a, $b) . "\n";
    print $interface->subtract($a, $b) . "\n";
}

// ------------------- main
// criação de 2 objetos do tipo Class1 e Class2
$c1 = new Class1();
$c2 = new Class2();
// chamada da função calculate
calculate(4, 3, $c1);
calculate(14, 13, $c2);
// uma interface não pode ser instanciada
try {
    new IExample();
} catch (\Error $e) {
    print "Error: " . $e->getMessage() . "\n";
}

Resultados:

1
2
3
4
5
6
> php interface-01.php
17
21
127
201
Error: Cannot instantiate interface Examples\IExample

Comentários

  • linhas 7–10: inclusão e declaração das classes e interfaces usadas pelo script. O arquivo [IExample.php] é incluído com a instrução [require_once]: ele será incluído apenas uma vez, mesmo que vários scripts do projeto o incluam;
  • Linhas 13–17: Uma função é definida;
  • Linha 13: Aqui, declaramos os tipos dos três parâmetros. Se, em tempo de execução, o parâmetro real não for do tipo esperado, um erro [TypeError] é lançado. O terceiro parâmetro é do tipo [IExample]. Isso significa que o parâmetro real deve ser uma instância de uma classe que implemente a interface [IExample]; portanto, em nosso exemplo, uma instância das classes [Class1] ou [Class2]. A função [calculate] não conhece essas classes; ela só conhece a interface. Podemos passar a ela objetos de classes escritas posteriormente, desde que implementem a interface [IExample];
  • linhas 15–16: usamos os métodos [add, subtract] da interface [IExample];
  • linha 24: o terceiro parâmetro real é do tipo [Class1], que é compatível com o tipo [IExample] do terceiro parâmetro formal da função;
  • linha 25: o mesmo vale para a classe [Class2];
  • linha 28: uma interface não pode ser instanciada; um erro é retornado (linha 6 dos resultados).

6.3. Derivando uma interface

Assim como uma classe filha pode estender uma classe pai, uma interface filha pode estender uma interface pai.

Considere a interface [IExample2] definida no arquivo [IExample2.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// namespace
namespace Examples;

// inclusão da definição da interface IExample
require_once __DIR__ . "/IExample.php";

// uma interface derivada de IExample
interface IExample2 extends IExample
{
    // o método adicionado pela interface
    public function multiply(int $i, int $j): int;
}

// implementação da interface IExample2
class Class3 extends Class2 implements IExample2
{
    // [Override] verifica se o método realmente existe na interface
    #[\Override]
    public function multiply(int $a, int $b): int
    {
        return $a * $b;
    }
}

Comentários

  • linha 7: a interface [IExample2] ficará no mesmo namespace que a interface [IExample];
  • linha 10: o arquivo de definição da interface [IExample] é incluído;
  • Linhas 13–17: definem a interface [IExample2], que estende ([extends]) a interface [IExample] e acrescenta a ela um novo método (linha 16). Uma interface pode até estender várias interfaces: [interface I3 extends I1, I2];
  • linhas 20–28: A classe [Class3] estende a classe [Class2]. Como esta última implementa a interface [IExample], a classe [Class3] também a implementará. De fato, [Class3] herda todos os métodos públicos e protegidos da classe [Class2], incluindo os métodos [add] e [subtract]. Além disso, especifica-se que [Class3] implementa a interface [IExample2]. Assim, ela também deve implementar o método [multiply], o que [Class2] não faz. É isso que as linhas 24–27 fazem;
  • linha 23: A partir do PHP 8.3, o atributo [#[\Override]], discutido no capítulo anterior, também se aplica a um método que implementa um método de interface. Se o método [multiply] desaparecesse da interface [IExample2], o PHP sinalizaria isso.

A interface [IExample2] é usada pelo seguinte script [interface-02.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// inclusão e declaração das classes e interfaces necessárias ao script
require_once __DIR__ . "/IExample2.php";
use Examples\IExample2;
use Examples\Class3;

// função
function calculate(int $a, int $b, IExample2 $interface): void
{
    print $interface->add($a, $b) . "\n";
    print $interface->subtract($a, $b) . "\n";
    print $interface->multiply($a, $b) . "\n";
}

// ------------------- main
// criação de 1 objeto do tipo Class3 que implementa IExample2
$c3 = new Class3();
// chamada da função calculate
calculate(4, 3, $c3);

Resultados:

1
2
3
4
> php interface-02.php
107
201
12

Comentários

  • Linha 12: O terceiro parâmetro da função [calculate] é do tipo [IExample2];
  • Linhas 14–16: Os três métodos da interface [IExample2] são usados: os dois herdados de [IExample] e o próprio dela;
  • linha 23: a função [calculate] é chamada com, como terceiro parâmetro, um objeto do tipo [Class3] que implementa [IExample2] (linha 21).

6.4. Passando uma interface como parâmetro de uma função

Vimos no capítulo anterior (na seção “Passando um objeto como parâmetro de uma função”) que, quando o tipo esperado para um parâmetro de função é uma classe, o parâmetro real pode ser um objeto do tipo esperado ou de um tipo derivado. O mesmo vale para as interfaces, como mostra o seguinte script, [interface-03.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// inclusão e declaração das classes e interfaces necessárias ao script
require_once __DIR__ . "/IExample.php";
require_once __DIR__ . "/IExample2.php";
use Examples\IExample;
use Examples\IExample2;
use Examples\Class1;
use Examples\Class3;

// função
function calculate(int $a, int $b, IExample $interface): void
{
    print $interface->add($a, $b) . "\n";
    print $interface->subtract($a, $b) . "\n";
}

// ------------------- main
// criação de 1 objeto do tipo Class3 que implementa IExample2 e, portanto, IExample
$c3 = new Class3();
// chamada da função calculate
calculate(4, 3, $c3);
// o operador [instanceof] testa se um objeto implementa uma interface
foreach ([new Class1(), $c3] as $object) {
    print $object::class . ": IExample=" . var_export($object instanceof IExample, true)
        . ", IExample2=" . var_export($object instanceof IExample2, true) . "\n";
}
// as interfaces implementadas pela classe Class3
print_r(class_implements($c3));

Resultados:

> php interface-03.php
107
201
Examples\Class1: IExample=true, IExample2=false
Examples\Class3: IExample=true, IExample2=true
Array
(
    [Examples\IExample] => Examples\IExample
    [Examples\IExample2] => Examples\IExample2
)

Comentários

  • Linha 15: A função [calculate] espera um tipo [IExample] como terceiro parâmetro. Isso significa que o parâmetro real pode ser do tipo [IExample] ou de um tipo derivado;
  • Linha 23: Um objeto do tipo [$c3] é instanciado a partir da classe [Class3], que implementa a interface [IExample2], a qual, por sua vez, estende a interface [IExample]. Assim, em última análise, [$c3] implementa a interface [IExample];
  • Linha 25: A função [calculate] é chamada com o objeto [$c3] (do tipo [Class3]) como terceiro parâmetro. Pela herança de classes e pelas implementações, vimos que o objeto [$c3] implementa o tipo [IExample]. Podemos, portanto, usá-lo como terceiro parâmetro;
  • linhas 27–30: O operador [instanceof] verifica se um objeto implementa uma interface. Um objeto do tipo [Class1] implementa [IExample] mas não [IExample2] (linha 4 dos resultados). Um objeto do tipo [Class3] implementa ambas (linha 5);
  • linha 32: A função [class_implements] retorna a lista de interfaces implementadas por um objeto ou classe, diretamente ou por herança (linhas 6–10 dos resultados).

6.5. Constantes de interface, várias interfaces e tipos de interseção

Uma interface também pode declarar constantes, e uma classe pode implementar várias interfaces. Definimos duas interfaces, [ICalculation] e [INameable], e duas classes que as implementam no arquivo [ICalculation.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// namespace
namespace Examples;

// uma interface pode declarar constantes
interface ICalculation
{
    // constante tipada (PHP 8.3)
    public const int PRECISION = 2;

    public function calculate(float $a, float $b): float;
}

// uma segunda interface
interface INameable
{
    public function getName(): string;
}

// uma classe pode implementar várias interfaces
final class Addition implements ICalculation, INameable
{
    #[\Override]
    public function calculate(float $a, float $b): float
    {
        return round($a + $b, self::PRECISION);
    }

    #[\Override]
    public function getName(): string
    {
        return "addition";
    }
}

final class Division implements ICalculation, INameable
{
    #[\Override]
    public function calculate(float $a, float $b): float
    {
        // [ICalculation::PRECISION] e [self::PRECISION] referem-se à mesma constante
        return round($a / $b, ICalculation::PRECISION);
    }

    #[\Override]
    public function getName(): string
    {
        return "division";
    }
}

Comentários

  • linha 13: A interface [ICalculation] declara uma constante. Todas as classes que implementam a interface a herdam. A partir do PHP 8.3, uma constante de classe ou de interface pode ser tipada (aqui, [int]);
  • Linhas 19–22: Uma segunda interface, com um único método;
  • linha 25: a classe [Addition] implementa as duas interfaces: os nomes das interfaces são separados por vírgulas. Ela deve definir os métodos de ambas;
  • linha 30: a constante herdada da interface é acessada por [self::PRECISION]. A função [round] arredonda um número para o número de casas decimais especificado;
  • linha 46: A constante também pode ser referenciada pelo nome da interface: [ICalculation::PRECISION].

Essas interfaces são usadas pelo script [interface-04.php]:

<?php

// respeito estrito aos tipos declarados dos parâmetros das funções
declare(strict_types=1);

// inclusão e declaração das classes e interfaces necessárias ao script
require_once __DIR__ . "/ICalculation.php";
use Examples\ICalculation;
use Examples\INameable;
use Examples\Addition;
use Examples\Division;

// o parâmetro [$calculation] tem um valor padrão: um objeto criado por [new] (PHP 8.1)
function execute(float $a, float $b, ICalculation $calculation = new Addition()): float
{
    return $calculation->calculate($a, $b);
}

// tipo interseção (PHP 8.1): [$operation] deve implementar as duas interfaces
function display(float $a, float $b, ICalculation&INameable $operation): void
{
    print $operation->getName() . "($a, $b)=" . $operation->calculate($a, $b) . "\n";
}

// ------------------- main
// constante da interface
print "precision: " . ICalculation::PRECISION . " decimal places\n";
// valor padrão do 3º parâmetro
print "execute(1.234, 2.345)=" . execute(1.234, 2.345) . "\n";
// parâmetro explícito
print "execute(10, 3, new Division())=" . execute(10, 3, new Division()) . "\n";
// tipo interseção
display(10, 4, new Division());
display(10, 4, new Addition());
// as classes implementam as duas interfaces
print_r(class_implements(Division::class));

Resultados:

> php interface-04.php
precision: 2 decimal places
execute(1.234, 2.345)=3.58
execute(10, 3, new Division())=3.33
division(10, 4)=2.5
addition(10, 4)=14
Array
(
    [Examples\ICalculation] => Examples\ICalculation
    [Examples\INameable] => Examples\INameable
)

Comentários

  • Linha 14: O terceiro parâmetro da função [execute] é do tipo [ICalculation] e tem um valor padrão — um objeto [Addition] criado com [new]. Até o PHP 8.0, o valor padrão de um parâmetro só podia ser uma constante. A partir do PHP 8.1, a expressão [new] é aceita em valores padrão de parâmetros (“new in initializers”), assim como nos argumentos de atributos do PHP ([#[...]]), em variáveis estáticas e em constantes globais. Ela continua proibida no valor padrão de um atributo de classe. O objeto é criado a cada chamada que omite o parâmetro;
  • linha 20: o tipo [ICalculation&INameable] é um tipo de interseção (PHP 8.1): o parâmetro real deve implementar tanto [ICalculation] quanto [INameable]. A função pode então chamar métodos das duas interfaces. Isso não deve ser confundido com o tipo de união [ICalculation|INameable] (um ou outro);
  • linha 27: a constante é acessível de fora pelo nome da interface (linha 2 dos resultados);
  • linha 29: o terceiro parâmetro é omitido; é um objeto [Addition] que realiza o cálculo (linha 3);
  • linha 31: um objeto [Division] é passado explicitamente (linha 4). Observe que os inteiros 10 e 3 são aceitos para parâmetros do tipo [float] apesar da declaração [strict_types=1]: a conversão de um ***[int] em um [float]*** é a única conversão automática permitida no modo estrito;
  • Linhas 33–34: Ambas as classes implementam ambas as interfaces; elas são aceitas pela função [display] (linhas 5–6);
  • linha 36: a notação [Division::class] representa o nome completo da classe, neste caso [Examples\Division]. A função [class_implements] aceita tanto um nome de classe quanto um objeto.

As interfaces são onipresentes no próprio PHP. Já encontramos duas no capítulo anterior: [Stringable], implementada automaticamente por qualquer classe que tenha um método [__toString], e [JsonSerializable], que permite controlar a codificação JSON de um objeto. No próximo capítulo, veremos a interface [Throwable], implementada por todos os erros e exceções. Uma enumeração também pode implementar uma interface. Por fim, veremos mais adiante neste curso que as interfaces formam a base da arquitetura em camadas de nossas aplicações: cada camada conhece apenas a interface da camada adjacente.