# Правила написания кода PHP-команды
> Битрикс24 · ORM · SOLID · DDD
> Полное руководство — версия 2.0
**Платформа:** Битрикс24
**PHP:** 8.1+ / 8.4
**Версия документа:** 2.0 (исправленная и дополненная)
**Год:** 2026
`SOLID` · `DRY` · `KISS` · `YAGNI` · `ORM Bitrix` · `DTO` · `Repository` · `PSR-3` · `PSR-12` · `PHP 8.1+` · `AbstractAgent`
---
## О руководстве
Это руководство описывает стандарты написания кода, принятые в PHP-команде. Оно опирается на принципы **SOLID, DRY, KISS, YAGNI** и адаптировано под специфику разработки на платформе **Битрикс24**.
Каждый раздел построен по принципу «плохо / хорошо»: вы видите конкретный антипаттерн и его корректную альтернативу с объяснением. Правила применяются ко всему новому коду и должны учитываться при рефакторинге существующего.
---
## Содержание
### Основные разделы
| № | Раздел | Ключевые темы |
|---|--------|---------------|
| 01 | [Именование и читаемость](./01-naming.md) | PSR-12, Bitrix-соглашения, UF_* поля |
| 02 | [Функции и методы](./02-functions.md) | SRP, ранний возврат, DTO, флаговые аргументы |
| 03 | [Классы и объекты](./03-classes.md) | SOLID, DI, ServiceLocator, композиция |
| 04 | [Контроллеры](./04-controllers.md) | тонкие контроллеры, DTO-валидация |
| 05 | [Работа с массивами и коллекциями](./05-arrays.md) | array_filter, array_column, Collections |
| 06 | [Условия и управляющие конструкции](./06-conditions.md) | match, Enum, Strategy, полиморфизм |
| 07 | [Типизация и строгость](./07-typing.md) | strict_types, readonly DTO, нативная типизация |
| 08 | [Обработка ошибок и Result Object](./08-errors.md) | доменные исключения, Bitrix Result |
| 09 | [Безопасность](./09-security.md) | ORM vs raw SQL, XSS, валидация входных данных |
| 10 | [Базы данных и ORM Битрикс](./10-database.md) | Repository, транзакции, N+1, fetchCollection |
| 11 | [Производительность: кеш и TaggedCache](./11-performance.md) | Cache, TaggedCache, select нужных полей |
| 12 | [Тестирование](./12-testing.md) | моки, DataProvider, изолируемые зависимости |
| 13 | [Комментирование и документация](./13-comments.md) | самодокументируемый код, PHPDoc |
| 14 | [Общие практики](./14-general.md) | DRY, KISS, YAGNI, Закон Деметры |
| 15 | [События Bitrix (EventManager)](./15-events.md) | тонкие подписчики, Event API |
| 16 | [Логирование (PSR-3)](./16-logging.md) | LoggerInterface, DI, уровни и контекст |
| 17 | [Агенты — AbstractAgent](./17-agents.md) | полный паттерн, регистрация, обработка ошибок |
### Тематические статьи (Tips)
Отдельные глубокие разборы конкретных конструкций и паттернов PHP/Bitrix:
| Статья | Описание |
|--------|----------|
| [Tips — все статьи](./tips/index.md) | Полный список тематических статей |
| [isset() vs empty()](./tips/isset-vs-empty.md) | Детальный разбор, таблица поведения, подводные камни |
---
## Принципы, которыми руководствуемся
**SOLID**
- **S** — Single Responsibility: каждый класс/функция — одна ответственность
- **O** — Open/Closed: открыт для расширения, закрыт для изменения
- **L** — Liskov Substitution: подтипы взаимозаменяемы
- **I** — Interface Segregation: маленькие специализированные интерфейсы
- **D** — Dependency Inversion: зависим от абстракций, не от реализаций
**Другие принципы**
- **DRY** — Don't Repeat Yourself: не дублируй знания
- **KISS** — Keep It Simple: простое решение лучше сложного
- **YAGNI** — You Aren't Gonna Need It: реализуй только то, что нужно сейчас
- **Закон Деметры** — не разговаривай с незнакомцами