Enum-классы WooCommerce вместо magic strings: что менять

2 сентября 2026 года команда WooCommerce опубликовала важное изменение для разработчиков расширений: ядро постепенно уходит от «магических строк» и предлагает публичные enum-классы в Automattic\WooCommerce\Enums.

Это касается кода, который сравнивает статусы заказов, типы товаров, состояние остатков, настройки и возможности платёжных шлюзов. Для магазинов с кастомными интеграциями тема особенно важна: одна строковая проверка часто запускает CRM, ERP, доставку или фискализацию.

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

Что меняет WooCommerce

Годами расширения писали проверки вроде 'completed' === $order->get_status(). Строки легко написать с ошибкой и сложнее централизованно документировать. Новые классы содержат именованные публичные константы.

use Automattic\WooCommerce\Enums\OrderStatus;

if ( OrderStatus::COMPLETED === $order->get_status() ) {
    // Заказ завершён.
}

Какие классы уже есть

Область	Примеры
Заказы	OrderStatus, OrderInternalStatus, OrderItemType
Товары	ProductType, ProductStatus, ProductStockStatus
Каталог	CatalogVisibility
Платежи	PaymentGatewayFeature
Настройки	WeightUnit, DimensionUnit, CurrencyPosition и другие

Почему это не native PHP enum

WooCommerce использует классы строковых констант, а не native enums. В официальном материале команда объясняет это совместимостью с большой существующей экосистемой и требованиями к загрузке кода.

Главная ловушка: OrderStatus и OrderInternalStatus

Эти классы не взаимозаменяемы. Один набор представляет непрефиксированные значения вроде completed, другой — внутренние варианты с wc-. Механическая замена всех строк может изменить семантику.

Как безопасно обновлять расширение

ИнвентаризацияНайти статусы, product types, stock state и settings strings
КонтекстОпределить источник каждого значения
СовместимостьПроверить минимальную версию WooCommerce
ЗаменаИспользовать только доступные публичные enum-классы
ТестыПрогнать checkout, статусы, возвраты и интеграции

Главный принцип: не делать глобальный Find & Replace без проверки контекста.

Нужно ли переписывать всё немедленно

Нет. Появление публичных констант не означает, что строковые значения мгновенно перестали работать. Новое API прежде всего делает свежий и поддерживаемый код менее хрупким.

Но если расширение поддерживает старые версии WooCommerce, нужно учитывать доступность классов. Иначе обращение к отсутствующему классу может закончиться fatal error.

Почему интеграции требуют отдельной проверки

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

Для таких задач A.S Groups занимается разработкой WooCommerce и интеграциями CRM.

Пример fallback для старой версии

use Automattic\WooCommerce\Enums\OrderStatus;

$completed = class_exists( OrderStatus::class )
    ? OrderStatus::COMPLETED
    : 'completed';

if ( $order->get_status() === $completed ) {
    // Бизнес-логика.
}

Что тестировать

создание заказа;
успешную и неуспешную оплату;
processing, completed, refunded и cancelled;
частичные возвраты;
синхронизацию товаров и остатков;
cron и webhook-обработчики;
внешние CRM/ERP логи.

Чек-лист для разработчика

Проверить минимальную версию WooCommerce
Найти magic strings в критичных ветках
Сверить актуальный список src/Enums
Не путать OrderStatus и OrderInternalStatus
Протестировать интеграции на staging
Обновить автоматические тесты

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

WooCommerce запретил строковые статусы?

Нет. Публичные enum-классы дают более документированный способ использовать те же значения.

Это native enum PHP 8.1?

Нет, это классы строковых констант.

Можно заменить completed на OrderInternalStatus::COMPLETED?

Не автоматически. Нужно учитывать наличие префикса wc-.

Изменение касается владельцев магазинов?

Косвенно да: кастомные интеграции нужно тестировать после обновлений.

Стоит ли рефакторить старый плагин?

Если он активно поддерживается — да, но с учётом совместимости.

Вывод

Enum-классы WooCommerce уменьшают количество хрупких строковых сравнений и делают API понятнее. Для старых интеграций это повод пересмотреть места, где статусы и типы объектов запускают бизнес-логику.

Если после обновления WooCommerce перестала работать интеграция или нужно обновить кастомный плагин, можно заказать доработку WordPress/WooCommerce или связаться с A.S Groups.

Официальные источники

Следующий шаг

Нужно решить похожую задачу?

CTA на аудит и доработку кастомных WooCommerce интеграций.

Обсудить задачу