Clean Code for 1C-Bitrix: Refactoring Without Risk
Typical scenario: init.php has grown to 3000 lines, direct SQL queries in template.php slow down pages, identical code is copied into 12 components. Adding a new field in the catalog requires edits in 8 places. This is technical debt, which reduces development speed and increases maintenance costs. We perform refactoring without changing external behavior, so the site continues to work the same, but the code becomes clean and maintainable. Our team has over 10 years of experience in 1C-Bitrix development and more than 50 successful refactoring projects.
Technical debt is a metaphor describing the extra costs of code maintenance caused by quick but suboptimal solutions. In Bitrix projects, it accumulates especially fast due to numerous integrations and custom logic. Budget savings on support can reach 60%—on average $5,000 to $15,000 per year for a typical project. For larger projects, savings can exceed $20,000 per year.
Why Refactoring Is Better Than Full Rewrite?
Full rewrite of a Bitrix project is a trap. Business logic accumulated over years in templates and handlers is not documented. Rewriting from scratch guarantees losing edge cases that were caught by hotfixes. The right approach is incremental refactoring: isolate one module, rewrite it, verify identical behavior, move on. Each iteration is a working site. Incremental refactoring is 2x cheaper and 3x faster than full rewrite. Compare:
| Criteria | Full Rewrite | Incremental Refactoring |
|---|---|---|
| Downtime risk | High (site down for weeks) | Low (each stage is a working site) |
| Time to result | Months | Days |
| Cost | High (everything rewritten) | Moderate (only problem areas) |
| Payback period | 6–12 months | 3–6 months |
Which Code Areas Need Refactoring First?
Priority 1 — decomposing init.php. A typical "bad" init.php contains event handlers, custom functions, classes, and direct initialization. The target state: init.php contains only require_once for the autoloader and handler registration. All logic goes into separate classes in /local/php_interface/classes/ or /local/modules/.
Structure of /local/:
/local/ php_interface/ init.php → autoloader + registration classes/ EventHandlers/ → Bitrix event handlers Helpers/ → utilities Services/ → business logic modules/ project.core/ → custom project module components/ → custom components templates/ → site templates Migration to /local/ is a standard Bitrix practice. Everything in /local/ takes precedence over /bitrix/, allowing kernel updates without conflicts. Investment in this stage usually pays back in 2–3 months by reducing time for modifications.
Priority 2 — moving logic out of component templates. A component template (template.php) should contain only HTML output. If it includes CIBlockElement::GetList(), $DB->Query(), or complex calculations, that's a problem. Three levels of refactoring:
-
result_modifier.php— transfer data preparation out oftemplate.php. -
class.php— create a component class extendingCBitrixComponent. - Custom component in
/local/components/project/— when the standard component no longer fits requirements.
Priority 3 — replacing direct SQL with D7 ORM. Direct queries via $DB->Query() mean no escaping, database vendor lock-in, and no caching. Switch to D7 ORM or parameterized queries. According to official 1C-Bitrix documentation, D7 ORM enables queries with automatic caching and SQL injection protection.
Priority 4 — eliminating duplication. Use phpcpd to find identical code blocks across different templates. Typical pattern: the catalog.section component has 5 templates with 80% identical code, differing only in CSS classes. Solution: one template with parameters or include files.
How to Refactor Without Downtime?
- Snapshot — create a backup and commit the current state in git.
- Testing — write smoke tests for critical pages (HTTP statuses, key elements).
- Replace — move one block of logic into a class, connect it, verify tests pass.
- Remove — delete old code after confirming tests pass.
- Deploy — push to production and monitor errors for 24 hours.
Typical Pitfalls in Refactoring
- Refactoring without VCS. Surprisingly, many Bitrix projects are still not in Git. The first refactoring step is initializing a repository with a correct
.gitignore(exclude/bitrix/,/upload/,/vendor/, keep/local/). - Switching to D7 "all at once." D7 API does not cover everything. Old API (
CIBlockElement,CSale*) works and is supported. Only transition code you are refactoring—do not touch working old code for "consistency". - Refactoring without monitoring. After deploying refactoring, watch
b_event_logand server logs. Errors may appear only under certain conditions: specific product type, user group, or browser.
Timeline Estimates
| Project Scale | Typical Refactoring Scope | Duration |
|---|---|---|
| Small (up to 50 custom files) | Decompose init.php, clean templates | 3–5 days |
| Medium (50–200 files) | + Replace SQL, remove duplicates | 1–2 weeks |
| Large (200+ files, custom modules) | + Migrate to /local/, modular architecture | 3–6 weeks |
Refactoring is an investment. Its effect is measured not visually, but in subsequent development speed and regression count during updates. To get a consultation and accurate estimate for your project, contact us. Order an audit right now.