PHP
#php#bitrix#option#union-types#typing#php-8

Bitrix: Option::get с union type возврата (PHP 8.x)

Обёртка над Bitrix\Main\Config\Option::get с явным возвращаемым типом string|int|bool|null для опций, свойств и полей инфоблоков.

Как использовать

  1. Скопируйте функцию getOption() в общий хелпер или конфиг проекта (например /local/php_interface/include/).
  2. Вызывайте getOption('имя_опции') вместо Option::get() там, где нужен типизированный результат (bool, int, string или null).
  3. Модуль и опция по умолчанию — main; при необходимости измените первый аргумент в Option::get внутри обёртки.

В 1С-Битрикс D7 метод \Bitrix\Main\Config\Option::get() всегда возвращает строку (документация). Опции модулей и настройки (флаги Y/N, числа, тексты) при этом логически могут быть булевыми, целыми или пустыми. При строгой типизации (PHP 8+, declare(strict_types=1)) и присвоении результата в переменную с типом bool|int возникают предупреждения или ошибки типов, а ручное приведение размазано по коду. Симптом: статический анализ или runtime ругаются на тип, либо везде дублируются проверки $v === 'Y' и ctype_digit(). Ниже — обёртка с union type возврата string|int|bool|null: одна точка приведения для опций, свойств и полей инфоблоков, плюс пример проверки.

Решение

Обёртка над Option::get() с явным возвращаемым типом. Подходит для опций модулей, свойств и полей, где на выходе может быть строка, число, флаг или пустое значение.

<?php

use Bitrix\Main\Config\Option;

/**
 * Получить опцию с явным типом возврата (PHP 8.0+).
 * Option::get() возвращает string; пустая строка или отсутствие — null.
 */
function getOption(string $name): string|int|bool|null
{
    $value = Option::get('main', $name, null);
    if ($value === null || $value === '') {
        return null;
    }

    // Флажок Y/N
    if ($value === 'Y' || $value === 'N') {
        return $value === 'Y';
    }

    // Целое число
    if (ctype_digit($value)) {
        return (int) $value;
    }

    return $value;
}

Пример использования:

// В конфиге/хелперах проекта
$useCache = getOption('cache_enabled');  // bool|null
$limit = getOption('list_limit');        // int|string|null
$name = getOption('site_name');          // string|null

Option::get($moduleId, $optionName, $default) — официальный API Bitrix D7. Третий аргумент — значение по умолчанию при отсутствии опции. ctype_digit() — встроенная функция PHP для проверки цифровой строки.

Проверка

  1. Проверка типов в консоли PHP (в корне сайта Bitrix, где подключается автозагрузчик):
cd /path/to/bitrix/site
php -r "
require_once __DIR__ . '/bitrix/modules/main/include/prolog_before.php';
require_once __DIR__ . '/local/php_interface/include/options_helper.php'; // путь к файлу с getOption
\$v = getOption('cache_enabled');
var_dump(\$v);
echo gettype(\$v) . PHP_EOL;
"

Подставьте реальный путь к файлу с функцией. Ожидаем: для опции Y/N — bool(true/false), для числа — int, для текста — string, при отсутствии — NULL.

  1. Диагностика: какое значение возвращает Option::get без обёртки — чтобы убедиться, что опция вообще есть:
// Временно в любом месте, где есть доступ к Bitrix
$raw = \Bitrix\Main\Config\Option::get('main', 'cache_enabled', '');
var_dump($raw); // строка "Y", "N" или пусто

После этого проверьте, что getOption('cache_enabled') даёт приведённый тип.

Типичные ошибки

  • Ошибка «Return type must be string» или несовместимость с объявленным типом — в проекте PHP меньше 8.0. Union types (string|int|bool|null) доступны с PHP 8.0. Обновите версию или уберите объявление возвращаемого типа и оставьте только приведение внутри функции.
  • Всегда null или неверный тип — опция хранится в другом модуле. В коде по умолчанию используется Option::get('main', $name, null). Для опций другого модуля либо передайте модуль параметром в getOption(), либо вызовите Option::get(‘module_id’, $name, null) внутри функции.
  • Числа с плавающей точкой — текущая логика распознаёт только целые (ctype_digit). Если опция может быть float, добавьте ветку с is_numeric() и (float) $value.

Где применять

  • Prod / dev: любой проект на 1С-Битрикс D7 с PHP 8.0+ и опциями модулей (main, iblock и др.), где нужна строгая типизация без размазанного приведения по коду.
  • Локально: подключайте файл с getOption через auto_prepend_file или в init.php/include в prolog_before.php.

Связанные сниппеты: Чтение и запись опций конфигурации, PHP 8.5: array first/last и выборка, Атрибут override в PHP 8.3.

Похожие сниппеты