Автозагрузка классов

Автозагрузка классов (autoloading) помогает системе автоматически находить и загружать необходимые классы. Это позволяет не подключать файлы вручную.

Подключить модулиПодключить модули

Метод Loader::includeModule() подключает установленный модуль: регистрирует пространство имен для папки lib/ и подключает файл include.php, если он существует. Файл lib/autoload.php метод не подключает. Для классов, которые следуют соглашению модуля, отдельная регистрация автозагрузки не нужна.

Загрузчик ищет папку модуля сначала в /local/modules/, затем в /bitrix/modules/. Если папка есть в /local/modules/, он использует ее. Повторный вызов в рамках одного запроса возвращает сохраненный результат и не подключает модуль заново.

// Подключим модуль CRM, который уже установлен в системе
if (\Bitrix\Main\Loader::includeModule('crm'))
{
    // Теперь можно работать с классами CRM
}
else
{
    // Обработка случая, когда модуль недоступен
    throw new \Exception('Не удалось подключить модуль CRM');
}

Метод возвращает значение:

• true — если модуль подключен,

• false — если модуль не установлен, его папка отсутствует или файл include.php вернул false.

При пустом или некорректном имени модуля метод выбрасывает исключение Bitrix\Main\LoaderException. Ошибки и исключения из кода include.php также не следует считать результатом false.

Если модуль обязателен для работы кода, используйте Loader::requireModule(). По умолчанию этот метод выбрасывает LoaderException, когда includeModule() возвращает false:

\Bitrix\Main\Loader::requireModule('crm');
// Теперь можно работать с классами CRM

Метод Loader::setRequireThrowException(false) отключает это поведение: requireModule() возвращает false при неудачном подключении. Проверка имени модуля продолжает выбрасывать исключение.

Разместить классы в lib/Разместить классы в lib/

Метод Loader::includeModule() определяет корневое пространство имен по идентификатору модуля:

• для имени без точки добавляет префикс Bitrix\ и переводит первую букву имени в верхний регистр: main → Bitrix\Main,

• для имени с точкой переводит первую букву каждой части в верхний регистр и заменяет точки на \: vendor.module → Vendor\Module.

Перед этим загрузчик переводит идентификатор модуля в нижний регистр. Корневое пространство имен соответствует папке lib/, остальные части имени класса — вложенным папкам и имени PHP-файла. Например, класс Vendor\Module\Controller\User из модуля vendor.module соответствует файлу /local/modules/vendor.module/lib/Controller/User.php.

Для новых классов сохраняйте регистр пространства имен в именах папок, а имя класса — в имени файла. Размещайте по одному классу в файле. Пример структуры модуля:

/local/modules/vendor.module/
└── lib/
    ├── Controller/
    │   └── User.php
    ├── Service/
    │   └── UserService.php
    └── Public/
        └── Event/
            └── UserCreatedEvent.php

Папки определяют подпространства имен: Service/UserService.php содержит класс Vendor\Module\Service\UserService, а Public/Event/UserCreatedEvent.php — класс Vendor\Module\Public\Event\UserCreatedEvent. Выбирайте структуру по задачам модуля. Загрузчик не требует фиксированного набора папок.

Например, контроллеры могут находиться в Controller/, как в статье Создание контроллера, или в Infrastructure/Controller/Web/, как в статье Контроллеры. Папка Public/Event/ из статьи События следует тому же правилу: путь после lib/ повторяет имя класса после корневого пространства имен модуля.

Загрузчик также поддерживает пути целиком в нижнем регистре. Для класса Vendor\Module\Controller\User он сначала проверяет lib/Controller/User.php, затем lib/controller/user.php. На файловой системе с учетом регистра смешанный вариант, например lib/Controller/user.php, не соответствует ни одному из этих путей. Используйте одинаковый регистр при объявлении класса и обращении к нему, чтобы загрузчик нашел файл.

Зарегистрировать класс для автозагрузкиЗарегистрировать класс для автозагрузки

Регистрируйте для автозагрузки классы, которые используются в большинстве сценариев, например, классы для работы с базой данных или обработки запросов. Это избавит систему от повторного поиска файлов. Классы для узких задач можно не регистрировать — они загрузятся автоматически при первом обращении, если следуют соглашению модуля.

Добавить классы в автозагрузку можно в файле /local/modules/[ваш_модуль]/include.php, который система подключает при вызове Loader::includeModule(). Явная карта классов позволяет загрузить класс из файла, путь к которому отличается от соглашения пространства имен.

/local/modules/mymodule/
├── include.php       // регистрируйте классы в файле include.php
├── lib/              // основные классы в папке lib
│   └── Main.php
└── classes/          // дополнительные классы в папке classes
    └── tools.php

Зарегистрировать класс можно методом Loader::registerAutoLoadClasses.

// В файле /local/modules/mymodule/include.php
\Bitrix\Main\Loader::registerAutoLoadClasses(
    'mymodule', // Имя вашего модуля
    [
        // Класс => относительный путь от папки модуля
        'MyModule\Main' => 'lib/Main.php',
        'MyModule\Tools' => 'classes/tools.php',
    ]
);

Зарегистрировать пространство имен по PSR-4Зарегистрировать пространство имен по PSR-4

PSR-4 — стандарт автозагрузки, который связывает префикс пространства имен с базовой папкой. После этого префикса каждый \ соответствует вложенной папке, а имя класса — имени файла с расширением .php. Регистр папок и файла должен совпадать с регистром соответствующих частей имени класса.

Метод Loader::registerNamespace() связывает префикс пространства имен с абсолютным путем к папке. Используйте его, если пространство имен или расположение классов отличается от соглашения модуля. Стандартное пространство имен модуля уже регистрирует includeModule().

Добавляйте регистрацию в файл /local/modules/[ваш_модуль]/include.php или в другой файл до первого обращения к классам из этого пространства. Файл include.php подключается при вызове includeModule() для модуля.

Зарегистрируйте дополнительное пространство имен:

\Bitrix\Main\Loader::registerNamespace(
    'MyCompany\MyModule', // Пространство имен
    \Bitrix\Main\Loader::getDocumentRoot() . '/local/modules/mymodule/lib' // Абсолютный путь
);

Как работает поиск классаКак работает поиск класса

1. Система проверяет, зарегистрирован ли класс для автозагрузки.

2. Если нет — ищет файл по PSR-4.

3. Если ни один загрузчик не нашел класс, PHP выдаст ошибку при обращении к нему.

Автозагрузка через ComposerАвтозагрузка через Composer

Composer — стандартный менеджер зависимостей для PHP, который позволяет управлять библиотеками и их версиями. В Bitrix Framework он используется для управления сторонними библиотеками и их автоматической загрузки.