PHP: полный мануал с примерами, функциями и ООП

<?php
declare(strict_types=1);

enum OrderStatus
{
    case New;
    case Paid;
}
$status = OrderStatus::Paid;
echo match ($status) {
    OrderStatus::New => 'Новый',
    OrderStatus::Paid => 'Оплачен',
}, "\n";

Оплачен

enum объявляет перечисление; case — один именованный вариант. :: выбирает его у типа. $status хранит объект этого варианта; new для enum не применяют. match сравнивает выбранный вариант и возвращает подпись. Enum появился в PHP 8.1.

<?php
declare(strict_types=1);

enum OrderStatus: string
{
    case New = 'new';
    case Paid = 'paid';
    public function label(): string
    {
        return match ($this) { self::New => 'Новый', self::Paid => 'Оплачен' };
    }
}
$status = OrderStatus::Paid;
echo 'Для БД: ', $status->value, "\n";
echo 'Для страницы: ', $status->label(), "\n";

Для БД: paid
Для страницы: Оплачен

: string задаёт скалярное значение для каждого case; это backed enum. value — его сохраняемое значение, name — имя Paid в коде. Все значения одного backed enum уникальны и одного объявленного типа: string либо int. Перевод подписи не требует менять сохранённый paid.

<?php
declare(strict_types=1);

enum OrderStatus: string { case New = 'new'; case Paid = 'paid'; }
class Order
{
    private OrderStatus $status = OrderStatus::New;
    public function markPaid(): string
    {
        if ($this->status === OrderStatus::Paid) { return 'Заказ уже оплачен'; }
        $this->status = OrderStatus::Paid;
        return 'Заказ отмечен оплаченным';
    }
}
$order = new Order();
echo $order->markPaid(), "\n";
echo $order->markPaid(), "\n";

Заказ отмечен оплаченным
Заказ уже оплачен

Enum не знает, когда допустимо менять состояние: правило находится в markPaid. Этот метод только показывает модель перехода; реальный заказ отмечают после проверенного подтверждения платежа. Идемпотентность платёжного запроса и транзакция БД требуют отдельной реализации.

<?php
declare(strict_types=1);

enum OrderStatus: string { case New = 'new'; case Paid = 'paid'; }
foreach (['paid', 'payed'] as $input) {
    $status = OrderStatus::tryFrom($input);
    echo $status === null ? 'Неизвестный статус: ' . $input : 'Фильтр: ' . $status->value;
    echo "\n";
}
try {
    OrderStatus::from('payed');
} catch (ValueError $error) {
    echo "В сохранённых данных неизвестный код\n";
}

Фильтр: paid
Неизвестный статус: payed
В сохранённых данных неизвестный код

tryFrom возвращает case или null для неизвестного значения подходящего типа. from возвращает case или бросает ValueError. Неподходящий тип входа может дать TypeError; tryFrom не обещает принять массив из формы. Перед вызовом проверяйте структуру внешнего ввода.

<?php
declare(strict_types=1);

final class PriceSnapshot
{
    public function __construct(public readonly int $kopecks) {}
}
$price = new PriceSnapshot(25900);
echo 'В заказе: ', $price->kopecks, " коп.\n";
try {
    $price->kopecks = 23900;
} catch (Error $error) {
    echo "Историческая цена защищена от перезаписи\n";
}

В заказе: 25900 коп.
Историческая цена защищена от перезаписи

readonly-свойство допускает инициализацию по правилам своей области, но запрещает обычную последующую запись. Тип обязателен. Оно не проверяет положительность цены: добавьте проверку конструктора, если цена приходит извне. Цена в заказе и сегодняшняя цена каталога могут различаться.

<?php
declare(strict_types=1);

class Address { public string $city = 'Тула'; }
class Snapshot
{
    public function __construct(public readonly Address $address) {}
}
$snapshot = new Snapshot(new Address());
$snapshot->address->city = 'Казань';
echo 'Адрес после изменения: ', $snapshot->address->city, "\n";

Адрес после изменения: Казань

Поле address по-прежнему содержит тот же объект, поэтому присваивания этому readonly-полю не было. Изменился вложенный Address. Для настоящего неизменяемого снимка нужен неизменяемый адрес либо отдельные скалярные поля.

<?php
declare(strict_types=1);

interface HasDeliveryLabel
{
    public function label(): string;
}

trait DeliveryDescription
{
    public function describe(): string
    {
        return 'Способ: ' . $this->label();
    }
}

enum DeliveryMethod implements HasDeliveryLabel
{
    use DeliveryDescription;

    case Pickup;
    case Courier;

    public const DEFAULT = self::Pickup;

    public function label(): string
    {
        return match ($this) {
            self::Pickup => 'Самовывоз',
            self::Courier => 'Курьер',
        };
    }

    public static function suggestedFor(int $weight): self
    {
        if ($weight < 0) {
            throw new InvalidArgumentException('Вес не может быть отрицательным');
        }
        return $weight > 10 ? self::Courier : self::Pickup;
    }
}

function printDelivery(HasDeliveryLabel $delivery): void
{
    echo $delivery->label(), "\n";
}

function defaultDelivery(DeliveryMethod $delivery = DeliveryMethod::DEFAULT): string
{
    return $delivery->name;
}

printDelivery(DeliveryMethod::suggestedFor(20));
echo DeliveryMethod::Pickup->describe(), "\n";
echo defaultDelivery(), "\n";
echo count(DeliveryMethod::cases()), "\n";

Курьер
Способ: Самовывоз
Pickup
2

SuggestedFor — наша политика учебной доставки, не встроенное правило enum. Статический метод возвращает существующий case. DEFAULT — ссылка на существующий Pickup, поэтому cases по-прежнему содержит два варианта, в порядке объявления. Case разрешён как значение константы и параметра по умолчанию.

<?php
declare(strict_types=1);

enum ShipmentCode: string
{
    case Ready = 'ready';
    case Sent = 'sent';
}

enum PickupPoint
{
    case North;
}

$status = ShipmentCode::Ready;
echo json_encode($status, JSON_THROW_ON_ERROR), "\n";
$saved = serialize($status);
$restored = unserialize($saved);
echo $restored === $status ? "Тот же case\n" : "Другой case\n";
try {
    json_encode(PickupPoint::North, JSON_THROW_ON_ERROR);
} catch (JsonException $error) {
    echo "Для pure enum нужен явный формат JSON\n";
}
echo json_encode(['point' => PickupPoint::North->name], JSON_THROW_ON_ERROR), "\n";
try {
    $copy = clone $status;
} catch (Error $error) {
    echo "Case нельзя клонировать\n";
}

"ready"
Тот же case
Для pure enum нужен явный формат JSON
{"point":"North"}
Case нельзя клонировать

Backed enum по умолчанию кодируется как своё value. Pure enum без JsonSerializable с JSON_THROW_ON_ERROR вызывает JsonException. В отдельной явной форме мы выбираем name сами. Серийная строка создана здесь же и доверена: этот опыт не разрешает принимать unserialize-ввод из запроса.

<?php
declare(strict_types=1);

enum InvoiceState: int
{
    case Issued = 10;
    case Paid = 20;
}

$state = InvoiceState::from(20);
echo $state->name, ': ', $state->value, "\n";
echo InvoiceState::tryFrom(99) === null ? "Неизвестный код\n" : "Код найден\n";
try {
    InvoiceState::from(99);
} catch (ValueError $error) {
    echo "Нельзя восстановить статус 99\n";
}
try {
    $state->value = 30;
} catch (Error $error) {
    echo "Код case изменить нельзя\n";
}

Paid: 20
Неизвестный код
Нельзя восстановить статус 99
Код case изменить нельзя

Каждая ветка показывает свою ситуацию. Null здесь не означает «счёт не оплачен»: он означает, что мы вообще не узнали статус. Value доступно только для чтения; нельзя и связать с ним изменяемую переменную через &.

<?php
declare(strict_types=1);

enum InvoiceState: int
{
    case Issued = 10;
    case Paid = 20;
}

require __DIR__ . '/weak-reader.php';
echo 'Нестрого: ', weakState('20')->name, "\n";
echo 'Нестрого, float: ', weakState(20.0)->name, "\n";
foreach (['20', 20.0, [20]] as $input) {
    try {
        InvoiceState::tryFrom($input);
    } catch (TypeError $error) {
        echo 'Строго: тип ', get_debug_type($input), " отклонён\n";
    }
}

function stateFromForm(mixed $raw): ?InvoiceState
{
    if (!is_string($raw) || !in_array($raw, ['10', '20'], true)) {
        return null;
    }
    return InvoiceState::from((int) $raw);
}

echo 'Проверенная форма: ', stateFromForm('20')?->name ?? 'ошибка', "\n";
echo stateFromForm('20abc') === null ? "Повреждённая строка отклонена\n" : "Принято\n";

Нестрого: Paid
Нестрого, float: Paid
Строго: тип string отклонён
Строго: тип float отклонён
Строго: тип array отклонён
Проверенная форма: Paid
Повреждённая строка отклонена

WeakState получает mixed и вызывает from именно из нестрогого файла. Число 20.0 выбрано без потери дробной части. Строгий tryFrom не заменяет проверку типа. Наш stateFromForm принимает только две разрешённые строки, затем намеренно переводит их в int. Это узкий договор формы с двумя вариантами, не универсальный разбор всех чисел.

<?php
declare(strict_types=1);

const CSV_CODE = 'csv';
enum ReportFormat: string
{
    case Csv = CSV_CODE;
    case Json = 'json';
}

const DEFAULT_REPORT = ReportFormat::Csv;
const DEFAULT_NAME = ReportFormat::Csv->name;
const DEFAULT_CODE = ReportFormat::Csv->value;

class ExportRequest
{
    public const DEFAULT_FORMAT = ReportFormat::Csv;
    public ReportFormat $format = ReportFormat::Csv;
}

function chooseFormat(ReportFormat $requested = ReportFormat::Csv): string
{
    static $last = ReportFormat::Csv;
    $previous = $last;
    $last = $requested;
    return $previous->value . ' -> ' . $requested->value;
}

echo DEFAULT_NAME, ': ', DEFAULT_CODE, "\n";
$request = new ExportRequest();
echo $request->format === DEFAULT_REPORT ? "Один вариант по умолчанию\n" : "Разные\n";
echo ExportRequest::DEFAULT_FORMAT->value, "\n";
echo chooseFormat(ReportFormat::Json), "\n";
echo chooseFormat(), "\n";

Csv: csv
Один вариант по умолчанию
csv
csv -> json
json -> csv

Case в значении const, свойства, параметра и static не клонируется. Локальная static хранит выбор только в текущем процессе и не сохраняет предпочтение пользователя между HTTP-запросами. CSV_CODE в backing value использует возможность PHP 8.2 ссылаться на константу.

<?php
declare(strict_types=1);

interface HasStandardTariff
{
    public static function standard(): self;
}

enum DeliveryTariff implements HasStandardTariff
{
    case Standard;
    case Express;

    public static function standard(): self
    {
        return self::Standard;
    }

    public function __invoke(int $goodsKopecks): int
    {
        if ($goodsKopecks < 0) {
            throw new InvalidArgumentException('Сумма товаров не может быть отрицательной');
        }
        return $goodsKopecks + ($this === self::Express ? 300 : 100);
    }
}

$tariff = DeliveryTariff::Express;
echo 'Прямой вызов: ', $tariff(1200), "\n";

function calculateOrder(callable $tariff, int $goodsKopecks): int
{
    return $tariff($goodsKopecks);
}

echo 'Обычный: ', calculateOrder(DeliveryTariff::standard(), 1200), "\n";
try {
    calculateOrder($tariff, -1);
} catch (InvalidArgumentException $error) {
    echo "Отрицательная сумма отклонена\n";
}

Прямой вызов: 1500
Обычный: 1300
Отрицательная сумма отклонена

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

<?php
declare(strict_types=1);

enum ShipmentPhase implements JsonSerializable
{
    case Ready;
    case Sent;

    public function jsonSerialize(): array
    {
        return match ($this) {
            self::Ready => ['code' => 'ready', 'label' => 'Ready for pickup'],
            self::Sent => ['code' => 'sent', 'label' => 'Handed over'],
        };
    }
}

echo json_encode(ShipmentPhase::Ready, JSON_THROW_ON_ERROR), "\n";
$saved = serialize(ShipmentPhase::Ready);
$same = unserialize($saved, ['allowed_classes' => false]);
echo $same === ShipmentPhase::Ready ? "Enum не отфильтрован allowed_classes\n" : "Заблокирован\n";

$oldSnapshot = str_replace(':Ready', ':Older', $saved);
$warned = false;
set_error_handler(function (int $level, string $message) use (&$warned): bool {
    if ($level !== E_WARNING || !str_starts_with($message, 'unserialize():')) {
        return false;
    }
    $warned = true;
    return true;
});
try {
    $restored = unserialize($oldSnapshot);
} finally {
    restore_error_handler();
}
echo $warned && $restored === false ? "Старый case не восстановлен\n" : "Неожиданный результат\n";

{"code":"ready","label":"Ready for pickup"}
Enum не отфильтрован allowed_classes
Старый case не восстановлен

Ready и Older имеют одинаковую длину: мы моделируем неизвестное имя, а не ошибочную длину PHP-строки. Allowed_classes не действует на enum; это не разрешение принимать недоверенную сериализацию. Пример не читает запросы или внешние файлы. Подробный текст предупреждения не становится ответом пользователю.