Composer в проекте Битрикс: подключение автозагрузки без конфликтов с ядром

Битрикс имеет собственный автолоадер, который конфликтует с Composer при неправильной настройке. Разберём как правильно подключить Composer-пакеты в Битрикс-проект, не ломая ядро и не получая ошибки класса Cannot redeclare.

Почему нельзя просто поставить Composer в корень

Если запустить composer install в корне сайта, автозагрузчик Composer начнёт конфликтовать с автолоадером Битрикс. Также vendor/ окажется в публичном доступе, что небезопасно.

Правильное место для Composer — директория /local/.

Структура проекта

/local/
  composer.json
  composer.lock
  vendor/          ← автозагрузчик и пакеты
  lib/             ← собственные классы
/bitrix/
  php_interface/
    init.php       ← подключаем vendor/autoload.php здесь

Инициализация Composer

cd /home/bitrix/www/local
composer init
# Отвечаем на вопросы: namespace, описание
# Vendor не должен быть в web root, но /local/ закрыт через nginx/apache

Пример composer.json

{
    "name": "mycompany/bitrix-local",
    "description": "Local modules and libraries",
    "require": {
        "guzzlehttp/guzzle": "^7.0",
        "vlucas/phpdotenv": "^5.5",
        "monolog/monolog": "^3.0"
    },
    "autoload": {
        "psr-4": {
            "MyCompany\\": "lib/"
        }
    },
    "config": {
        "vendor-dir": "vendor"
    }
}

Подключение в init.php

Закрываем /local/vendor/ от публичного доступа
Для Nginx:
location ^~ /local/vendor/ {
    deny all;
    return 404;
}
Для Apache (.htaccess в /local/vendor/):
Order deny,allow
Deny from all
Пример использования Guzzle в компоненте
 "https://api.example.com"]);

try {
    $response = $client->get("/users", [
        "headers" => ["Authorization" => "Bearer " . TOKEN],
        "timeout" => 10,
    ]);
    $data = json_decode($response->getBody(), true);
} catch (\GuzzleHttp\Exception\RequestException $e) {
    AddMessage2Log($e->getMessage(), "my_module");
}
Собственные классы через PSR-4
calculate(2.5, "Москва");
Обновление зависимостей
cd /home/bitrix/www/local

# Установить зависимости (первый раз или после git pull)
composer install --no-dev --optimize-autoloader

# Добавить новый пакет
composer require league/csv:^9.0

# Обновить все пакеты
composer update
Добавляем vendor в .gitignore
# .gitignore
/local/vendor/
Коммитим только composer.json и composer.lock. На сервере запускаем composer install как часть деплоя.
Итог
Ключевые правила: Composer в /local/, подключение автолоадера через init.php, /vendor/ закрыт от публичного доступа. После этого любые Composer-пакеты работают в Битрикс-проекте без конфликтов.