bitrix-result-and-errors

Result and Error

Baseline: main 23.0+ · Verified: main 26.800.0

Contract

• Expected failures (validation, business rule, not found, no rights) → Result with Errors.
• Broken state or contract (module missing, DB down, misconfiguration, bug) → exception.
• One method, one contract: always a Result, or a value plus exceptions for the exceptional case. Never 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('Title required', 'BLOG_POST_TITLE_EMPTY', ['field' => 'title']));
}

return $result->setData(['id' => $id]);

• isSuccess(), addError(Error), addErrors(Error[]), getErrors(), getError() (first or null), getErrorMessages(), getErrorCollection(), setData(array), getData(). Setters return $this.
• setData() silently drops SqlExpression values.

Error and codes

new Error($message, $code = 0, $customData = null). JSON form: {"message", "code", "customData"}.

• Codes are stable and machine-readable: module + entity + reason (BLOG_POST_NOT_FOUND), kept in constants. Clients branch on the code, not the text.
• Messages via Loc::getMessage('BLOG_ERROR_POST_TITLE_EMPTY').
• ErrorCollection: new ErrorCollection([$error]), setError(), add([...]), getErrorByCode('CODE'), iterable, isEmpty(), toArray().

Typed result

Give callers getters instead of 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 results (Bitrix\Main\ORM\Data\*)

• AddResult: getId(), getPrimary(), getObject().
• UpdateResult: getId(), getPrimary(), getAffectedRowsCount().
• DeleteResult: no methods of its own (no affected-rows count).
• Bitrix\Main\Entity\*Result are compat aliases. Write ORM\Data\*.
• A failed ORM result whose errors nobody read (isSuccess() / getErrors()) raises E_USER_WARNING on destruct. Always check it and return it, or copy its errors up.