Работа с результатом выполнения функций - \Bitrix\Main\Result()

Часто нужно, чтобы функция возвращала какой-то результат выполнения. К примеру функция создания чего-то в базе данных возвращает id этой записи. И удобно когда функция всегда возвращает данные одного типа, например int. Но не всегда функция создания может успешно добавлять данные, тогда мы бы в ответе получаем false, это уже тип bool, а мы ожидаем int - это первая проблема. И вторая проблема - хорошо бы еще знать по какой причине не удалось создать запись в базе данных.

Решить эти проблемы можно если возвращать объект \Bitrix\Main\Result() и большинство методов D7 возвращают этот объект или от него наследуемый.

Методы класса  \Bitrix\Main\Result():

$result = new \Bitrix\Main\Result();

$data = ['id' => 123];
//Добавляет данные, на входе должен быть массив.
$result->setData($data);
//Вернёт массив, который был добавлен через setData() - ['id' => 123]
$returnData = $result->getData();

//Создаём объект ошибки.
$error = new \Bitrix\Main\Error('Текст ошибки', 'error_code', ['key1' => 'value', 'key2' => 'value2']);
$error2 = new \Bitrix\Main\Error('Текст ошибки2', 'error_code2');
$error3 = new \Bitrix\Main\Error('Текст ошибки3');
//Добавление ошибки, просто текст ошибки нельзя передать, только объект \Bitrix\Main\Error();
$result->addError($error);
//Можно добавить сразу несколько ошибок.
$result->addErrors([$error2, $error3]);
//Получить ошибки в виде массива объектов \Bitrix\Main\Error()
$errors = $result->getErrors();
//Получить ошибки в виде объекта \Bitrix\Main\ErrorCollection();
$errorCollection = $result->getErrorCollection();
//Получить массив с текстами ошибок
$errorMessages = $result->getErrorMessages();
/*
 * $errorMessages будет содержать только тексты ошибок:
 * Array
 *  (
 *      [0] => Текст ошибки
 *      [1] => Текст ошибки2
 *      [2] => Текст ошибки3
 *  )
 */

//Вернет true если не были добавлены ошибки, в противном случае - false
$result->isSuccess();

Методы \Bitrix\Main\Error()

$error = new \Bitrix\Main\Error('Текст ошибки', 'error_code', ['key1' => 'value', 'key2' => 'value2']);
//Получение текста ошибки - вернет 'Текст ошибки'
$errorMessage = $error->getMessage();
//Получение кода ошибки - вернет 'error_code'
$errorCode = $error->getCode();
//Получение данных ошибки - вернет ['key1' => 'value', 'key2' => 'value2'], не обязательно массив передавать, можно и другие типы данных.
$errorData = $error->getCustomData();
//Получить все данные объекта в виде массиво
$arError = $error->jsonSerialize();
/**
 *  $arError
 *  Array
 *  (
 *      [message] => Текст ошибки
 *      [code] => error_code
 *      [customData] => Array
 *      (
 *          [key1] => value
 *          [key2] => value2
 *      )
 *  )
 */

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

/** 
 * @param array $fields
 * @return \Bitrix\Main\Result
 * @throws Exception
 */
function addSection(array $fields)
{
    $result = new Bitrix\Main\Result();
    if (!$fields['NAME']) {
        $result->addError('Не указано название раздела', 'empty_name', $fields);

        return $result;
    }

    $addResult = Bitrix\Iblock\SectionTable::add($fields);
    //Если успешно создан раздел, то пробрасываем данные, иначе пробрасываем ошибки
    if($addResult->isSuccess()) {
        $result->setData($addResult->getData());
    } else {
        $result->addErrors($addResult->getErrors());
    }

    return $result;
}

$fields = [
    'NAME' => 'Раздел1',
    'CODE' => 'section1',
    'IBLOCK_ID' => 1
];

$result = addSection($fields);
if($result->isSuccess()) {
    echo 'Успешно создан раздел';
    var_dump($result->getData());
} else {
    echo 'Ошибка создания раздела:';
    echo implode('<br>',$result->getErrorMessages());
}