PHPTime

Интерфейсы, трейты и перечисления (enum) в PHP

Интерфейс задаёт контракт, трейт позволяет переиспользовать реализацию, а перечисление ограничивает набор допустимых значений. Разберём, где применять каждый механизм, как они сочетаются и какие особенности PHP 8.3–8.5 влияют на совместимость кода.

Интерфейс PHP (interface): контракт для разных реализаций

Интерфейс объявляется ключевым словом interface. Он задаёт публичные методы и может содержать константы. Класс принимает контракт через implements, а интерфейс может расширять несколько других интерфейсов через extends. Один класс может реализовать несколько интерфейсов.

Типизируйте параметр интерфейсом, когда вызывающему коду важна операция, а реализация может меняться. В этом примере расчёт суммы зависит от правил скидки, поэтому их можно выбирать при вызове.

PHP
<?php
declare(strict_types=1);

interface DiscountPolicy
{
    public function discountFor(int $amount): int;
}

final class TenPercentDiscount implements DiscountPolicy
{
    public function discountFor(int $amount): int
    {
        // Суммы передаются в копейках, дробная часть скидки отбрасывается.
        return intdiv($amount, 10);
    }
}

function totalAfterDiscount(int $amount, DiscountPolicy $policy): int
{
    return $amount - $policy->discountFor($amount);
}

echo totalAfterDiscount(12_500, new TenPercentDiscount()); // 11250

Публичный контракт можно принять в параметре, вернуть из функции или сохранить в типизированном свойстве. PHP проверяет принадлежность к интерфейсу: класс с совпадающими именами и сигнатурами методов тоже должен явно объявить implements или унаследовать реализацию контракта.

Совместимость сигнатур и ошибки с interface

Реализация обязана предоставить все требуемые методы. Абстрактный класс может отложить часть реализации до конкретного подкласса. Если два интерфейса объявляют одноимённый метод, его сигнатура должна одновременно удовлетворять обоим контрактам.

  • Видимость и статичность. Метод интерфейса реализуется как public. Статический метод остаётся статическим, экземплярный — экземплярным.
  • Параметры. Реализация может принять более общий тип. Например, параметр object совместим с требованием принимать DateTimeImmutable. Дополнительные параметры должны быть необязательными. Нельзя делать необязательный параметр обязательным.
  • Возвращаемое значение. Реализация может вернуть более конкретный тип. Например, DateTimeImmutable подходит для контракта с типом возврата DateTimeInterface.
  • Именованные аргументы. Сохраняйте имена параметров из интерфейса. PHP допускает их переименование в реализации, но вызов с прежним именем аргумента может завершиться ошибкой Unknown named parameter.

Расширение типа параметра называется контравариантностью, сужение возвращаемого типа — ковариантностью. Несовместимая сигнатура приводит к фатальной ошибке при объявлении класса. declare(strict_types=1) для этой проверки не требуется. Директива управляет проверкой скалярных аргументов при вызовах из файла, где она объявлена.

Свойства в интерфейсах с PHP 8.4

Интерфейс может потребовать публичное чтение свойства через { get; }, публичную запись через { set; } или обе операции. Для реализации подходит обычное публичное свойство, если оно поддерживает требуемые операции и совместимо по типу. PHP 8.4 также позволяет реализовать требование со свойством с хуками. Объявление ниже требует PHP 8.4 или 8.5.

PHP
<?php
declare(strict_types=1);

interface HasLabel
{
    public string $label { get; }
}

final class Category implements HasLabel
{
    // Обычное публичное свойство можно читать через контракт.
    public function __construct(public readonly string $label) {}
}

function printLabel(HasLabel $item): void
{
    echo $item->label;
}

printLabel(new Category('Книги'));

Для библиотеки с минимальной версией PHP 8.3 выражайте то же требование методом public function label(): string;. Если потребители должны записывать значение, объявите отдельный метод для записи.

Трейт PHP (trait): общая реализация для классов

Трейт объявляется ключевым словом trait и подключается через use внутри класса. Он может содержать методы, свойства, константы и абстрактные методы. Создать экземпляр трейта или использовать его как тип параметра нельзя. При подключении его методы становятся частью класса и могут обращаться к его членам через $this.

PHP
<?php
declare(strict_types=1);

trait FormatsLabel
{
    // Класс предоставляет значение, трейт отвечает за форматирование.
    abstract protected function rawLabel(): string;

    public function formattedLabel(): string
    {
        return '[' . trim($this->rawLabel()) . ']';
    }
}

final class ProjectTag
{
    use FormatsLabel;

    public function __construct(private readonly string $label) {}

    protected function rawLabel(): string
    {
        return $this->label;
    }
}

echo (new ProjectTag(' PHP '))->formattedLabel(); // [PHP]

Абстрактный метод делает зависимость трейта явной: конкретный класс должен предоставить совместимую реализацию. Такой приём удобен для общей логики, которой нужны данные объекта. Если поведение включает заменяемую зависимость, например отправку сообщений через разных провайдеров, передайте объект с подходящим интерфейсом через конструктор.

Конфликты методов и свойств в trait

Для обычного переопределяемого метода приоритет такой: собственный метод класса, затем метод трейта, затем унаследованный метод. Если два подключённых трейта предоставляют одноимённый метод, конфликт нужно разрешить явно. insteadof выбирает основную реализацию, а as добавляет псевдоним или меняет видимость. Псевдоним сохраняет исходное имя метода, поэтому одного as для устранения конфликта недостаточно.

PHP
<?php
declare(strict_types=1);

trait PlainLabel
{
    public function label(): string { return 'PHP'; }
}

trait DetailedLabel
{
    public function label(): string { return 'Язык PHP'; }
}

final class LabelPresenter
{
    use PlainLabel, DetailedLabel {
        // Основной метод берём из PlainLabel, второй доступен по псевдониму.
        PlainLabel::label insteadof DetailedLabel;
        DetailedLabel::label as detailedLabel;
    }
}

$presenter = new LabelPresenter();
echo $presenter->label(), PHP_EOL, $presenter->detailedLabel();
  • Одноимённые свойства. Если трейт и класс объявляют одноимённое свойство, определения должны быть совместимы, включая тип, видимость и значение по умолчанию. Для разных данных выбирайте разные имена либо оставляйте свойство в одном месте.
  • Статическое состояние. Начиная с PHP 8.3, если родитель и потомок оба подключают трейт со статическим свойством, у потомка появляется отдельное свойство. В PHP 8.2 они использовали общее свойство. Проверьте этот сценарий при переносе счётчиков и кешей.
  • Запрет переопределения. С PHP 8.3 подключаемый метод можно пометить final, например use PlainLabel { label as final; }. Это запрещает переопределять импортированный метод в потомках класса.

Перечисления PHP (enum): конечный набор значений

Перечисление объявляется ключевым словом enum, а его варианты — через case. Каждый вариант является единственным экземпляром своего перечисления. Его можно передавать в типизированные функции и сравнивать через ===. Все варианты имеют доступное для чтения свойство name с именем, указанным в объявлении.

  • Обычное перечисление подходит для выбора стратегии или режима внутри программы. Достаточно объявить варианты, например enum SortOrder { case Asc; case Desc; }.
  • Перечисление со скалярными значениями (backed enum) подходит для обмена данными с API или БД. Выберите один тип основы, string или int, и задайте каждому варианту уникальное значение этого типа. Оно доступно через value.
PHP
<?php
declare(strict_types=1);

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Cancelled = 'cancelled';

    public function label(): string
    {
        // Названия для интерфейса отделены от значений, хранимых в БД.
        return match ($this) {
            self::Pending => 'Ожидает оплаты',
            self::Paid => 'Оплачен',
            self::Cancelled => 'Отменён',
        };
    }
}

$status = OrderStatus::from('paid');
echo $status->label(); // Оплачен

OrderStatus::cases() возвращает все варианты в порядке объявления. Метод доступен и у обычных перечислений. Перечисление может реализовывать интерфейсы и подключать трейты без свойств. У самого перечисления нельзя объявить собственные свойства или конструктор. При сравнении используйте $status === OrderStatus::Paid, а для сравнения со строкой обращайтесь к $status->value.

Как разбирать внешние значения enum

У перечислений с типом основы есть два метода обратного преобразования. from() возвращает вариант либо выбрасывает ValueError, если допустимого скалярного значения нет. Он подходит для данных, где неизвестное значение означает нарушение контракта. tryFrom() в том же случае возвращает null, чтобы вызывающий код мог обработать ошибку ввода.

PHP
<?php
declare(strict_types=1);

// OrderStatus объявлен в предыдущем примере.
function parseOrderStatus(mixed $input): OrderStatus
{
    // Данные из запроса могут оказаться массивом или числом.
    if (!is_string($input)) {
        throw new InvalidArgumentException('Статус должен быть строкой.');
    }

    return OrderStatus::tryFrom($input)
        ?? throw new InvalidArgumentException('Неизвестный статус заказа.');
}

echo parseOrderStatus('paid')->value; // paid
  • tryFrom() может выбросить TypeError. При строгой типизации для строкового перечисления передавайте строку, для целочисленного — int. Проверяйте тип входных данных перед вызовом.
  • Храните значение value. Используйте его для записи в БД и формирования внешнего ответа. Изменение значения уже используемого варианта требует согласования с потребителями данных и, при необходимости, миграции.
  • Обновляйте match при добавлении варианта. Если подходящей ветки нет и отсутствует default, PHP выбросит UnhandledMatchError. Когда у каждого варианта своя логика, явные ветки помогают заметить пропущенное изменение.

Совместимость с PHP 8.3, 8.4 и 8.5

ВерсияЧто учитывать
PHP 8.3Атрибут #[\Override] выявляет методы, которые должны реализовать метод интерфейса или переопределить унаследованный метод, но не имеют соответствующего объявления. Для трейтов применяются отдельное статическое свойство при повторном подключении в потомке и синтаксис as final.
PHP 8.4Интерфейс может требовать чтение и запись публичных свойств. Применение этого синтаксиса повышает минимальную версию проекта до 8.4.
PHP 8.5Атрибут #[\Override] можно применять и к свойствам. Основные примеры interface, trait и enum выше сохраняют совместимость.

Перечисления доступны с PHP 8.1. Для проекта, который заявляет поддержку 8.3–8.5, проверяйте синтаксис и тесты на каждой заявленной версии. Это особенно важно для библиотек, где минимальную версию PHP определяет ограничение в composer.json.

Чек-лист выбора interface, trait и enum

  1. Операция с несколькими реализациями. Объявите интерфейс и принимайте его в параметре или конструкторе. Проверьте типы, видимость и имена параметров.
  2. Общий фрагмент реализации. Вынесите его в трейт. Объявите нужные методы как абстрактные и проверьте конфликты имён при подключении.
  3. Конечный набор допустимых значений. Объявите enum. Если значения пересекают границу приложения, задайте стабильные string или int значения и валидируйте вход.
  4. Несколько задач в одном классе. Сочетайте механизмы там, где у каждого есть роль. Например, класс может реализовать интерфейс обработчика заказов, подключать трейт форматирования и принимать OrderStatus как аргумент.

Частые вопросы

Чем interface отличается от trait в PHP?

Интерфейс задаёт публичный контракт и служит типом для параметров, свойств и возвращаемых значений. Трейт подключает общую реализацию к классу через use. Класс может реализовать интерфейс методом, который он получает из трейта.

Как получить список значений PHP enum?

Вызовите OrderStatus::cases(), чтобы получить массив вариантов в порядке объявления. У каждого варианта есть свойство name. Если перечисление имеет тип основы string или int, у вариантов также есть свойство value.

Чем from() отличается от tryFrom() в PHP enum?

Оба метода возвращают вариант перечисления со скалярным значением. Если такого варианта нет, from() выбрасывает ValueError, а tryFrom() возвращает null. При аргументе неподходящего типа возможен TypeError.

Справка по теме

Ещё в разделе «Справочник PHP»

Исключения в PHP: try, catch, finally и свои классы ошибок

Как работают исключения в PHP 8.3–8.5: try, catch, finally и throw, перехват Exception и Error, собственные классы и типичные ошибки обработки.

9 мин

Как добавить и удалить элемент массива в PHP

Как добавить и удалить элемент массива в PHP 8, сохранить или переиндексировать ключи, получить первый и последний элементы с reset(), end() и без них.

8 мин

Как запустить PHP-файл: встроенный сервер, CLI и локальное окружение

Как создать и запустить PHP-файл из терминала или открыть его в браузере через localhost. Примеры для PHP 8.3–8.5, настройка сервера и разбор ошибок.

9 мин

Как узнать и обновить версию PHP: phpinfo, CLI и хостинг

Как узнать версию PHP через phpinfo(), CLI и панель хостинга, выбрать ветку PHP 8.3–8.5 и обновить сайт с проверкой расширений и совместимости.

8 мин