Ядро / Result, ошибки и логирование

Result

Bitrix\Main\Result — стандартный способ вернуть успех или список ошибок.

isSuccess

<?php

use Bitrix\Main\Result;

/**
 * Проверяет результат операции.
 */
function handleOperationResult(Result $result): array
{
    return [
        'is_success' => $result->isSuccess(),
        'error_messages' => $result->getErrorMessages(),
    ];
}

getErrorMessages

Для вывода пользователю или записи в лог обычно удобнее брать уже готовые строки ошибок.

<?php

/**
 * Возвращает текст ошибок через перенос строки.
 */
function buildErrorText(\Bitrix\Main\Result $result): string
{
    return implode(PHP_EOL, $result->getErrorMessages());
}

Свой Result

<?php

use Bitrix\Main\Error;
use Bitrix\Main\Result;

/**
 * Проверяет входной ID и возвращает Result.
 */
function validateEntityId(int $entity_id): Result
{
    $result = new Result();

    if ($entity_id <= 0) {
        $result->addError(
            new Error('ID сущности не заполнен')
        );
    }

    return $result;
}

$result = validateEntityId($entity_id);

if (!$result->isSuccess()) {
    print_r($result->getErrorMessages());
}

Ошибки

Для служебных скриптов лучше оборачивать основной код в try-catch.

try-catch

<?php

use Bitrix\Main\Diag\Debug;

/**
 * Пишет исключение в лог.
 */
function writeExceptionLog(\Throwable $exception): void
{
    Debug::dumpToFile(
        [
            'message' => $exception->getMessage(),
            'file' => $exception->getFile(),
            'line' => $exception->getLine(),
            'trace' => $exception->getTraceAsString(),
        ],
        'exception',
        '/local/logs/exceptions.log'
    );
}

try {
    // Основной код
} catch (\Throwable $exception) {
    writeExceptionLog($exception);
}

Error и ErrorCollection

Если нужно не просто текстовое сообщение, а код ошибки, можно использовать Bitrix\Main\Error.

<?php

use Bitrix\Main\Error;
use Bitrix\Main\Result;

/**
 * Возвращает ошибку с кодом.
 */
function buildFailedResult(string $message, string $code): Result
{
    $result = new Result();

    $result->addError(
        new Error($message, $code)
    );

    return $result;
}

$result = buildFailedResult('Недостаточно данных', 'EMPTY_REQUIRED_FIELDS');

print_r($result->getErrors());

Логирование

Для AJAX, cron, агентов и обработчиков событий удобнее писать в файл, а не выводить на экран.

Debug::dumpToFile

<?php

use Bitrix\Main\Diag\Debug;

/**
 * Пишет данные в debug-файл.
 */
function writeDebugData($data, string $label): void
{
    Debug::dumpToFile(
        $data,
        $label,
        '/local/logs/debug.log'
    );
}

writeDebugData(
    [
        'deal_id' => 123,
        'status' => 'start',
    ],
    'crm_debug'
);

AddMessage2Log

AddMessage2Log() часто встречается в старом коде и быстрых проверках.

<?php

/**
 * Пишет сообщение в лог старым способом.
 */
function writeOldBitrixLog(string $message, array $context = []): void
{
    AddMessage2Log(
        [
            'message' => $message,
            'context' => $context,
        ],
        'custom_debug'
    );
}

writeOldBitrixLog('Проверка обработчика', ['deal_id' => 123]);

Единая функция лога

<?php

use Bitrix\Main\Diag\Debug;

const LOG_FILE = '/local/logs/custom.log';

/**
 * Пишет сообщение в единый лог.
 */
function writeLogMessage(string $message, array $context = []): void
{
    Debug::dumpToFile(
        [
            'date' => date('Y-m-d H:i:s'),
            'message' => $message,
            'context' => $context,
        ],
        'log',
        LOG_FILE
    );
}

writeLogMessage('Скрипт запущен', ['user_id' => 1]);