Strategy — Incremental Bitrix D7 Migration

When to use

• The task adds a new D7 ORM entity, event handler, or module class into a project that still contains legacy Bitrix code.
• The task is to modernize a legacy Bitrix codebase toward the D7 API — moving from CIBlockElement-style access to ORM entities, events, or the module structure.
• Пользователь просит перевести старый код Битрикса на D7 постепенно, по одному модулю или сущности, не переписывая весь проект сразу.

When NOT to use

• Do not apply the incremental-migration strategy to a brand-new Bitrix project written on D7 from the start, where there is no legacy code to migrate.
• Do not apply this strategy to a project that does not use Bitrix, since the D7 API and its migration concerns are Bitrix-specific.

Core guidance

• Use the D7 ORM for newly migrated reads and writes — For the entity you are migrating, route new reads and writes through the D7 ORM DataManager while leaving untouched entities on their legacy access.
• Bridge behavior through D7 events, not core edits — When new behavior must react to legacy actions, hook it through the D7 event system rather than editing legacy core files in place.
• Keep the legacy path working during migration — Keep the legacy Bitrix code functioning until every consumer has moved to the D7 path, so the site never depends on an unfinished migration.
• Introduce a seam and strangle the legacy path — Wrap the legacy access behind a small interface, add a D7 implementation behind the same seam, and switch consumers over one at a time.
• Verify the portal after each migration step — After migrating each entity or consumer, verify the affected pages and admin functions still work before moving to the next step.

Never

• Never rewrite a whole Bitrix project from legacy to D7 in one sweep; a big-bang migration of a live portal risks breaking unrelated modules all at once.

Prefer

• Prefer migrating one entity or module to D7 at a time — introduce a D7 ORM entity or event handler beside the legacy code and cut consumers over gradually.

Avoid

• Avoid interleaving legacy CIBlock-style calls and D7 ORM within the same function; keep a clear seam so each unit is clearly on the old or the new path.

Escalate to user when

• Escalate to the user before migrating shared kernel or core module code that many components depend on, since the blast radius spans the whole portal.

Quick recipe

1. Choose a single entity to migrate, wrap its current legacy access in a small interface, and route existing consumers through that seam without changing behavior yet. (verify: The chosen entity's consumers call the seam, and the portal still behaves exactly as before over the legacy implementation.)
2. Add a D7 ORM implementation behind the same seam, switch consumers to it one at a time verifying after each, and remove the legacy implementation only once the last consumer has moved. (verify: Each consumer works on the D7 path after its cutover, the portal is verified at every step, and legacy is removed only after the final consumer migrates.)

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Legacy and D7 writing the same data inconsistently — During coexistence, a legacy path and a D7 path writing the same records can drift if they apply different rules or caches. Fix: Route all writes for a migrated entity through a single path and treat the other as read-only until the cutover is complete.
2. Editing Bitrix core files that updates overwrite — Modifying files under the Bitrix core during a migration means the next platform update silently reverts the changes. Fix: Put migration logic in your own module or in D7 event handlers, and never edit core files in place.
3. Forgetting to include the module before D7 calls — Calling a D7 ORM entity without first including its module leaves the class unavailable and fails at runtime. Fix: Include the required module through the loader before using its D7 classes, and handle the case where inclusion fails.

Version notes

• Incremental-migration discipline is version-agnostic (PHP >=7.4) — Migrating Bitrix legacy code to D7 incrementally is a strategy that applies across PHP versions Bitrix supports; it constrains how the agent sequences the migration, not which language features it uses, so it holds from PHP 7.4 upward.

Security

• Not applicable — no I/O, auth, or untrusted input.

Testing

• Activation and decision behavior are verified in eval/scenarios/ai-rules/strategy-bitrix-d7-incremental.yaml.

Additional resources

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

Knowledge graph

Related: ai-rules/strategy-legacy-safe-edits, ai-rules/strategy-minimal-diff, bitrix/d7-events, bitrix/d7-orm-queries