Composer в Битрикс: полное руководство по установке и настройке

Composer — стандартный менеджер зависимостей для PHP. В мире Битрикс он открывает доступ к современным инструментам разработки: ORM-аннотациям, CLI-интерфейсу, сторонним библиотекам и фреймворкам. В этой статье разберем, как правильно организовать работу с Composer в проекте на Битрикс, где разместить файлы конфигурации и защитить их от внешнего доступа.

Зачем Composer в Битрикс

Битрикс — это зрелая платформа с собственной архитектурой. Но современные PHP-проекты требуют использования сторонних библиотек: для работы с API, логирования, тестирования, работы с изображениями. Composer решает эту задачу элегантно:

• Автоматическая установка зависимостей — указали в composer.json нужные пакеты, выполнили composer install, и все библиотеки скачались
• Контроль версий — фиксируете конкретные версии пакетов, гарантируя стабильность проекта
• Автозагрузка классов — не нужно вручную подключать файлы через require, Composer генерирует автозагрузчик
• Воспроизводимость — любой разработчик может развернуть проект с теми же зависимостями

В Битрикс Composer особенно полезен для:

• Подключения ORM-аннотаций (doctrine/annotations)
• Использования CLI-инструментов (symfony/console)
• Интеграции внешних API-клиентов (guzzlehttp/guzzle)
• Разработки собственных модулей с зависимостями

Где разместить файлы

Варианты размещения

По умолчанию система ищет файл composer.json в папке /bitrix/. Размещение там технически работает, но разработчики Битрикс рекомендуют использовать папку /local/ для проектной конфигурации.

Причины:

• Папка /bitrix/ — это ядро системы. Обычно битрикс-разработчики там свой код и файлы не размещают, за редкими исклчениями.
• Папка /local/ — кастомный код проекта, не затрагивается при обновлениях. Лучшая практтика для размещения своих классов, можулей и компонентов.
• Разделение ядра и проектного кода — лучшая практика

Рекомендуемая структура: /local/composer/

Оптимальный вариант, на мой взгляд, создать отдельную папку для Composer внутри /local/:

/local/
├── composer/                  # Папка для Composer
│   ├── composer.json          # Основной файл конфигурации
│   ├── composer.lock          # Зафиксированные версии зависимостей
│   └── vendor/                # Установленные пакеты (создается автоматически)
├── php_interface/
│   ├── init.php               # Точка входа для инициализации
│   └── autoload.php           # Подключение автозагрузчика Composer (опционально)
└── modules/                   # Ваши кастомные модули

Преимущества такой структуры:

• Изоляция Composer от остального кода в /local/
• Легко найти все файлы, связанные с зависимостями
• Удобно для командной работы: видно, где находится конфигурация

Создание файла конфигурации

В ядре Битрикс есть готовый файл-пример /bitrix/composer.json.example. Его можно скопировать как основу:

Этот файл содержит базовую структуру с учетом особенностей Битрикс и уже настроенное слияние с composer-bx.json.

{
"require": {
"wikimedia/composer-merge-plugin": "dev-master"
},
"extra": {
"merge-plugin": {
"require": [
"путь_к_папке_bitrix/composer-bx.json"
]
}
}
}

Разберем основные директивы:

• require — список зависимостей и их версий. "wikimedia/composer-merge-plugin": "dev-master": Этот атрибут указывает, что для работы проекта необходим плагин composer-merge-plugin от Wikimedia. Версия dev-master означает, что будет загружена самая свежая ветка разработки (master) напрямую из репозитория.
• extra — Используется для конфигурации сторонних плагинов. В данном случае здесь настраивается плагин, объявленный выше.
• merge-plugin — Конфигурационный блок для плагина слияния. "require": [ "путь_к_папке_bitrix/composer-bx.json" ]: Этот атрибут указывает плагину автоматически импортировать (сливать) настройки и зависимости из другого, изолированного файла конфигурации Битрикса. Это позволяет разделять зависимости самого ядра Битрикса и вашего кастомного кода.

Стандартные зависимости Битрикс

В ядре Битрикс есть файл /bitrix/composer-bx.json, который содержит список стандартных зависимостей платформы. Это не отдельный composer.json, а дополнение к нему.

Эти зависимости уже протестированы с Битрикс и гарантированно работают. Вместо того чтобы вручную добавлять их в свой composer.json, используйте механизм слияния через плагин wikimedia/composer-merge-plugin.

Подключение автозагрузчика

После установки зависимостей Composer создает автозагрузчик в файле /local/composer/vendor/autoload.php. Чтобы Битрикс использовал эти зависимости, нужно подключить автозагрузчик. Есть два способа.

Способ 1: Через .settings.php (рекомендуемый)

Файл .settings.php — это конфигурационный файл Битрикс, который загружается на ранних этапах инициализации. Через него можно указать путь к composer.json, и Битрикс автоматически подключит автозагрузчик.

Откройте файл /bitrix/.settings.php и добавьте или измените секцию composer:

return [
    // ... другие настройки ...
    
    'composer' => [
        'value' => [
            'config_path' => '/local/composer/composer.json'
        ]
    ],
    
    // ... другие настройки ...
];

Путь config_path указывается относительно корня сервера. Битрикс сам найдет vendor/autoload.php рядом с composer.json и подключит его.

Способ 2: Через init.php (альтернативный)

Если по каким-то причинам не хотите использовать .settings.php, можно подключить автозагрузчик вручную через /local/php_interface/init.php:

<?php
// Подключение автозагрузчика Composer
$composerAutoload = $_SERVER["DOCUMENT_ROOT"] . '/local/composer/vendor/autoload.php';
if (file_exists($composerAutoload)) {
    require_once $composerAutoload;
}

Этот способ работает, но менее предпочтителен, так как init.php загружается позже, чем .settings.php.

Установка зависимостей

Для установки Composer используйте официальную инструкцию.

После установки перейдите в терминале в папку с вашим composer.json (например, /local/composer/) и выполните:

composer install

Composer прочитает composer.json, скачает все зависимости в папку vendor/ и создаст composer.lock с зафиксированными версиями.

composer.lock: зачем он нужен

Файл composer.lock содержит точные версии всех установленных пакетов. Это гарантирует, что все разработчики и серверы используют одинаковые версии зависимостей.

Обновление зависимостей

Для обновления пакетов до последних совместимых версий:

composer update

Для добавления нового пакета:

composer require vendor/package-name

Composer автоматически обновит composer.json и composer.lock.

Защита от внешнего доступа

Файлы composer.json и composer.lock содержат информацию о вашем проекте: используемые библиотеки, их версии, структуру. Эта информация может быть полезна злоумышленникам для поиска уязвимостей.

Проблема: файлы доступны через браузер

Если composer.json лежит в /local/composer/composer.json, а веб-сервер настроен на отдачу всех файлов из этой папки, то любой может открыть https://your-site.com/local/composer/composer.json и увидеть вашу конфигурацию.

Защита через .htaccess (Apache)

Создайте файл /local/.htaccess:

# Запретить доступ к файлам конфигурации
<Files "composer.json">
    Require all denied
</Files>

<Files "composer.lock">
    Require all denied
</Files>

# Запретить доступ ко всем JSON-файлам (опционально)
<Files "*.json">
    Require all denied
</Files>

Если используете структуру с папкой composer/, можно создать .htaccess внутри нее:

# Запретить доступ ко всей папке
Require all denied

Если используете nginx

Если используете nginx, добавьте в конфигурацию сервера:

location ~ ^/local/composer/(composer\.json|composer\.lock)$ {
    deny all;
    return 403;
}

# Или запретить всю папку composer
location ~ ^/local/composer/ {
    deny all;
    return 403;
}

Перемещение файлов за пределы DOCUMENT_ROOT

Самый надежный способ — разместить файлы конфигурации за пределами публичной директории.

/home/bitrix/ # Путь от корня к сайту
├── composer/              # Папка за пределами DOCUMENT_ROOT
│   ├── composer.json
│   ├── composer.lock
│   └── vendor/
└── www/                   # DOCUMENT_ROOT
    ├── bitrix/
    └── local/

В этом случае веб-сервер физически не сможет отдать файлы, так как они находятся вне публичной папки.

Настройте путь в .settings.php:

return [
    'composer' => [
        'value' => [
            'config_path' => '/home/bitrix/composer/composer.json'
        ]
    ],
];

Проверка защиты

После настройки попробуйте открыть composer.json через браузер:

https://your-site.com/local/composer/composer.json

Должна появиться ошибка 403 Forbidden или 404 Not Found. Если файл открывается — защита не работает.

Заключение

Composer в Битрикс — мощный инструмент, который открывает доступ к современной PHP-экосистеме. Правильная организация проекта с размещением composer.json в /local/composer/, использование composer-bx.json для стандартных зависимостей и защита конфигурации от внешнего доступа — основа стабильной работы.

Ключевые моменты:

• Размещайте composer.json в /local/composer/ или /local/, а не в /bitrix/
• Используйте merge-plugin для слияния с composer-bx.json через относительные пути
• Подключайте автозагрузчик через .settings.php (рекомендуемый способ) или init.php
• Защищайте composer.json и composer.lock от доступа через браузер
• Коммитьте composer.lock в Git, но не коммитьте vendor/