Migrating a website to a new version of 1C-Bitrix

Migration to a New 1C-Bitrix Version

Upgrading Bitrix from version 16 to 22 is not simply "click update" in the administrative panel. Over years of operation, a website accumulates non-standard modules, deprecated APIs, and templates built on legacy core. Attempting an update without preparation often ends with a white screen in production. Proper migration is a phased process with a test environment and rollback capability.

What Changes Between Versions

Bitrix actively migrates from the old core (D5/kernel) to D7. Key breaking changes during upgrades:

• Old catalog API (CIBlockElement, CCatalog) is replaced by ORM-classes Bitrix\Iblock\ElementTable, Bitrix\Catalog\*
• CUser is partially replaced by \Bitrix\Main\User* — authentication methods have changed
• bitrix:catalog component in versions 20+ has been refactored with SKU support; old templates require adaptation
• sale module — order architecture changed from version 17 (Order, Basket, Shipment are now objects instead of arrays)
• PHP — Bitrix 23+ requires PHP 8.0+; legacy code with preg_replace('/e', ...) and each() fails

Migration Stages

Stage 1. Current State Audit

Before any upgrade — complete inventory:

• List of non-standard modules (/local/modules/, custom modules in /bitrix/modules/)
• Marketplace modules with compatibility check for target version
• Custom component templates in /local/templates/ and /bitrix/templates/
• Usage of deprecated functions: grep -r "CIBlockElement::" /local/ --include="*.php"
• Server PHP version

Stage 2. Test Stand

A complete copy of the website is set up on a separate server or domain. On the test stand:

1. Back up files and database
2. Perform incremental update via administrative panel (System Update)
3. Fix all errors from /bitrix/cache/ and PHP logs

Stage 3. Module Compatibility

For each third-party Marketplace module — verify compatible version on the developer portal. If no update exists — contact the developer or rewrite functionality.

For custom modules — manual adaptation. Typical changes:

// Old (legacy core):
$dbResult = CIBlockElement::GetList([], $filter, false, false, $select);

// New (D7 ORM, Bitrix 22+):
$result = \Bitrix\Iblock\ElementTable::getList([
    'filter' => $filter,
    'select' => $select,
]);

Stage 4. Template Adaptation

Catalog component templates are the main pain point. In Bitrix 20+, the bitrix:catalog component changed its $arResult structure. Variable $arResult['ITEMS'] is replaced with $arResult['CATALOG_ITEMS'] with new SKU structure.

Template adaptation accounts for 40–60% of total migration time.

Stage 5. Functionality Testing

Testing checklist:

• Add product to cart
• Checkout (each step)
• Personal account — order history
• Catalog search
• Product filtering
• Payment (all configured payment systems)
• 1C synchronization
• Email notifications
• Administrative section — product editing

Stage 6. Production Migration

Optimal scenario:

1. Maintenance window (notify users in advance)
2. Production backup
3. Update Bitrix via update_system_step.php with sequential step progression
4. Apply prepared module and template patches
5. Run full testing checklist
6. Return to normal operation

Typical Problems

Execution Timeline

Version migration is planned technical maintenance, not a one-time disaster. With proper preparation, production downtime is 2–4 hours.