Bitrix Iblock Elements

When to use

• The user needs to create, read, update, or delete Bitrix information block elements and asks whether to use the D7 ORM (\Bitrix\Iblock\Elements\ElementTable) or the legacy CIBlockElement.
• Пользователь строит список элементов инфоблока с фильтром по активности, дате или свойству (getList в D7 ORM или CIBlockElement::GetList) и спрашивает, как безопасно передать пользовательский ввод в фильтр.
• The user needs to read or write iblock element properties (single, multiple, or list values) — via the D7 PropertyValues collection or the legacy CIBlockElement::GetProperty / SetPropertyValues.

When NOT to use

• Do not use this skill for Highload block entities or arbitrary module ORM tables that are not information block elements; their storage and API differ.
• Do not use this skill on a non-Bitrix PHP app; information blocks, CIBlockElement, and \Bitrix\Iblock\... exist only inside 1C-Bitrix.

Core guidance

• Never build filter keys from untrusted input — Pass user input only as filter values through the array filter (D7 filter or legacy $arFilter); never interpolate user input into filter keys, operators, field names, or a runtime/raw SQL expression.
• Prefer the D7 iblock ORM for new element code — In new code, read and write elements through the D7 ORM (\Bitrix\Iblock\Elements\ElementTable or a generated Element<CODE>Table) instead of CIBlockElement::GetList / CIBlockElement::Add.

Decision Engine

Walk this section before choosing an implementation path.

Are you writing new element code, or editing an existing legacy CIBlockElement path?

├── Editing legacy path: → legacy — keep the existing CIBlockElement call and make a minimal local edit; do not rewrite to the ORM opportunistically.

└── New code: Does the operation need a legacy-only feature (workflow/BizProc hooks, `CIBlockElement::Add` side effects, deep GetList mode)?

    ├── No legacy-only feature: → d7 — use ElementTable/getList with select, filter, and PropertyValues; pass user input only as filter values.

    └── Needs legacy-only feature: → legacy — call CIBlockElement (e.g. Add/Update with workflow) behind a thin repository so call sites stay D7-shaped.

Full engine: references/decision-engine.md — Decision Tree, Priority Matrix, Decision Table.

Workflows

Workflow: Create Element D7

Progress:
- [ ] Include iblock, then resolve the element entity for the iblock — a generated
`Element<CODE>Table` or `\Bitrix\Iblock\Elements\ElementTable` compiled for the
iblock id
- [ ] Create the object, set fields (`$el->setName($name); $el->setIblockId($id);
$el->setActive('Y');`) and set property values through the object's
`PropertyValues` collection with validated data
- [ ] Call `$result = $el->save();` and branch on `$result->isSuccess()`, reading
`$result->getErrorMessages()` on failure instead of assuming success

1. Include iblock, then resolve the element entity for the iblock — a generated Element<CODE>Table or \Bitrix\Iblock\Elements\ElementTable compiled for the iblock id.
   • Verify: The entity class corresponds to the target iblock and is loaded after includeModule.
2. Create the object, set fields ($el->setName($name); $el->setIblockId($id); $el->setActive('Y');) and set property values through the object's PropertyValues collection with validated data.
   • Verify: Required fields and properties are set from validated values before saving.
3. Call $result = $el->save(); and branch on $result->isSuccess(), reading $result->getErrorMessages() on failure instead of assuming success.
   • Verify: Save success is checked and errors are surfaced, not swallowed.

Workflow: Read List D7

Progress:
- [ ] Include the module with
`if (!\Bitrix\Main\Loader::includeModule('iblock')) { return; }` before
referencing any element class
- [ ] Read the request value through the kernel Request and cast it, e.g
- [ ] Call `ElementTable::getList(['select' => ['ID', 'NAME'], 'filter' =>
['=ACTIVE' => 'Y', '=IBLOCK_SECTION_ID' => $sectionId], 'limit' => 20]);` and
iterate the typed result

1. Include the module with if (!\Bitrix\Main\Loader::includeModule('iblock')) { return; } before referencing any element class.
   • Verify: Element classes are only reached when the iblock module is present.
2. Read the request value through the kernel Request and cast it, e.g. $sectionId = (int) $request->getQuery('section');, rejecting non-positive ids.
   • Verify: The value is an int bound to a fixed filter key, never a user-chosen key.
3. Call ElementTable::getList(['select' => ['ID', 'NAME'], 'filter' => ['=ACTIVE' => 'Y', '=IBLOCK_SECTION_ID' => $sectionId], 'limit' => 20]); and iterate the typed result.
   • Verify: Only rendered fields are selected, ACTIVE is enforced, and paging is bounded.

Best practices

• On the public frontend, filter lists with ACTIVE => 'Y' and respect the activity dates (ACTIVE_DATE_FROM/ACTIVE_DATE_TO, or the ORM equivalent) so drafts and expired elements are not shown; only admin/edit contexts may drop them
• Guard element access with \Bitrix\Main\Loader::includeModule('iblock') (or the legacy CModule::IncludeModule('iblock')) and bail out when it returns false, before referencing CIBlockElement or any \Bitrix\Iblock\... class
• For a list, select only the fields and properties you render and page with limit/offset (D7) or nPageSize (legacy); for a detail view load the single element by id and its properties in one pass
• Read D7 element properties via the object's getValue() on the PropertyValues collection (or a withProperties/->fill() load); in legacy code use CIBlockElement::GetProperty / GetElementValues in bulk rather than one call per property per row

Anti-patterns

See references/anti-patterns.md.

Debugging

1. User input flowing into a filter key or field — Bitrix parameterizes filter values but emits keys, fields, and raw expressions into SQL verbatim. Fix: Keep filter keys, fields, and operators as constants in code; whitelist any input-selected field against a fixed allow-list and bind only validated values.
2. Forgetting the active filter on public lists — Bitrix does not filter inactive or future-dated elements automatically at the query layer. Fix: Add =ACTIVE => 'Y' plus the activity-date conditions (or reuse the component's standard public filter) on every frontend list, restricting the unfiltered query to admin contexts.
3. Fetching properties one element at a time — Per-row property fetches scale linearly with the result set and dominate page time. Fix: Select the needed properties with the list query (D7 PropertyValues / withReferences) or use CIBlockElement::GetElementValues to bulk-load property values for all ids at once.
4. Ignoring the result of an element write — A silent write failure leaves the caller believing data was persisted when it was not. Fix: For legacy, check the return value and read $el->LAST_ERROR; for the ORM, branch on $result->isSuccess() and surface getErrorMessages().

Performance notes

• Fetching properties one element at a time — Calling CIBlockElement::GetProperty (or reloading the ORM property collection) inside a list loop issues one or more queries per row, an N+1 explosion on large lists.
• Select only needed fields for lists, full record for detail — For a list, select only the fields and properties you render and page with limit/offset (D7) or nPageSize (legacy); for a detail view load the single element by id and its properties in one pass.
• Access properties through the proper collection, not GetNext loops — Read D7 element properties via the object's getValue() on the PropertyValues collection (or a withProperties/->fill() load); in legacy code use CIBlockElement::GetProperty / GetElementValues in bulk rather than one call per property per row.

Production checklist

• Every public-facing element list enforces ACTIVE => 'Y' and the activity-date bounds so drafts and expired elements never reach visitors.
• List queries select only the fields and properties actually rendered and use paging (limit/offset or nPageSize), with no per-row property fetches in a loop.
• Filter keys, field names, and operators are constants in code; only validated, cast values derive from user input, and any input-selected field is whitelisted.
• Edits to legacy CIBlockElement paths are minimal and reversible, with no opportunistic rewrite into the D7 ORM during an unrelated change.
• Every element access is preceded by a checked Loader::includeModule('iblock') (or legacy equivalent) that bails out cleanly when the module is absent.
• Every create/update checks its outcome — legacy return value plus $el->LAST_ERROR, or the ORM $result->isSuccess() — before the caller treats the data as persisted.

Version notes

• The iblock ORM supersedes CIBlockElement on modern cores — The D7 iblock ORM (\Bitrix\Iblock\Elements\ElementTable and generated Element<CODE>Table entities) is the current API on modern cores (iblock ~20+); CIBlockElement remains as the legacy facade that older code and some workflow-aware writes still rely on.
• PHP support tracks the Bitrix core version — Modern Bitrix cores run the iblock module on PHP 7.4 through 8.2; the module and its ORM were not certified past 8.2 at the time of writing, so avoid relying on PHP 8.3+ syntax in iblock-adjacent code.

Security

• Treat iblock filter input as an injection boundary — Treat every request value used in an element filter as untrusted: validate and cast it, bind it only as a filter value under a fixed key, and never let input choose a field name, operator, or feed a runtime/raw SQL expression.

Testing

• Activation and decision behavior are verified in eval/scenarios/bitrix/iblock-elements.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/decision-engine.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Prerequisites: bitrix/d7-orm-queries
Related: bitrix/cache-layers

Skill contract

Produces: iblock.elements-accessed
Requires: bitrix.iblock-module-available, bitrix.d7-orm-available
Risk: medium · Confidence: 0.9