bitrix-result-and-errors
Используй для контрактов сервисов Битрикса: Main\Result, Error, ErrorCollection и стабильные коды ошибок. AddResult/UpdateResult ORM, ответы контроллера и границы исключений.
How do I install this agent skill?
npx skills add https://github.com/bxmaximum/bitrix-framework-skills --skill bitrix-result-and-errorsIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides coding guidelines for handling results and errors in the Bitrix framework. It includes security best practices such as avoiding the exposure of secrets, SQL queries, or internal file paths in error messages sent to clients. No security issues were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Result и Error
Baseline: main 23.0+ · Verified: main 26.1000.0
Перед PHP-кодом прочитай bitrix-framework, если ещё не читал его в этой задаче.
Контракт
- Ожидаемый отказ (валидация, бизнес-правило, отсутствие записи или прав) →
ResultсError. - Нарушенное состояние/контракт (нет модуля, БД недоступна, неверная конфигурация, ошибка кода) → исключение.
- Один метод — один контракт: всегда
Resultлибо значение с исключениями для исключительных ситуаций. Не смешивайbool/null/-1/['error' => …].
Bitrix\Main\Result
use Bitrix\Main\Error;
use Bitrix\Main\Result;
$result = new Result();
if ($title === '')
{
return $result->addError(new Error('Нужен заголовок', 'BLOG_POST_TITLE_EMPTY', ['field' => 'title']));
}
return $result->setData(['id' => $id]);
isSuccess(),addError(Error),addErrors(Error[]),getErrors(),getError()(первая ошибка либоnull),getErrorMessages(),getErrorCollection(),setData(array),getData(). Сеттеры возвращают$this.setData()молча отбрасывает значенияSqlExpression.
Error и коды
new Error($message, $code = 0, $customData = null). Форма JSON: {"message", "code", "customData"}.
- Коды стабильны и пригодны для программной обработки: модуль + сущность + причина (
BLOG_POST_NOT_FOUND), хранятся в константах. Клиент выбирает поведение по коду, не по тексту. - Сообщения получай через
Loc::getMessage('BLOG_ERROR_POST_TITLE_EMPTY'). ErrorCollection:new ErrorCollection([$error]),setError(),add([...]),getErrorByCode('CODE'), перебор,isEmpty(),toArray().
Типизированный результат
Предоставляй методы чтения вместо getData()['post']:
final class CreatePostResult extends \Bitrix\Main\Result
{
private ?Post $post = null;
public function setPost(Post $post): self
{
$this->post = $post;
return $this;
}
public function getPost(): ?Post
{
return $this->post;
}
}
Результаты ORM (Bitrix\Main\ORM\Data\*)
AddResult:getId(),getPrimary(),getObject().UpdateResult:getId(),getPrimary(),getAffectedRowsCount().DeleteResult: своих методов нет, включая число затронутых строк.Bitrix\Main\Entity\*Result— псевдонимы совместимости. ИспользуйORM\Data\*.- Неуспешный результат ORM, ошибки которого никто не прочитал (
isSuccess()/getErrors()), при уничтожении вызываетE_USER_WARNING. Всегда проверяй его и возвращай либо передавай ошибки выше.
$add = PostTable::add(['TITLE' => $title]);
if (!$add->isSuccess())
{
return (new Result())->addErrors($add->getErrors());
}
$id = $add->getId();
Другие результаты
EventResult(SUCCESS,ERROR,UNDEFINED) — ответ обработчика, а не результат сервиса (bitrix-events).ValidationResult(bitrix-validation) наследуетResult: добавляй его ошибки в результат сервиса.
Контроллеры
$this->addErrors($result->getErrors()); return null; даёт {"status":"error","data":null,"errors":[…]}. Обёртка описана в bitrix-controllers.
Исключения на границе
Перехватывай на границе модуля/контроллера, записывай в лог и возвращай общую ошибку:
try
{
return $this->service->run($dto);
}
catch (\Bitrix\Main\SystemException $e)
{
$this->logger->error('Выполнение завершилось ошибкой', ['exception' => $e]);
return (new Result())->addError(new Error('Внутренняя ошибка', 'VENDOR_INTERNAL_ERROR'));
}
- Не поглощай
\Throwableбез записи в журнал. - Ошибки разработчика (
InvalidArgumentException,LogicException,TypeError) и невозможные состояния предметной области (деление на ноль в денежном типе) остаются исключениями.
Текст исключений в AJAX (Since main 26.1000)
В Engine\Controller при exception_handling.debug=false обычное исключение становится Internal server error. с исходным кодом; PHP Error также скрывается. ArgumentNullException сохраняет текст с кодом ERROR_REQUIRED_PARAMETER, а BinderArgumentException, ArgumentException, ValidationException сохраняют сообщение. Явные addError(Error) и ошибки ValidationException передаются клиенту: не включай в них SQL, секреты и внутренние пути. При debug=true подробности открыты.
До 26.1000 такого общего скрытия нет: перехватывай исключения на границе и возвращай безопасный Error, как выше. Для ожидаемого отказа используй стабильный код Result, а не RuntimeException с текстом для пользователя.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/bxmaximum/bitrix-framework-skills/bitrix-result-and-errors">View bitrix-result-and-errors on skillZs</a>