Composer

Composer — это инструмент управления зависимостями в PHP, который позволяет устанавливать, обновлять и управлять сторонними библиотеками и пакетами, необходимыми для вашего проекта. Его основная задача — автоматизировать процесс поиска и установки необходимых компонентов, а также их обновления. Composer работает с пакетом зависимостей на основе файла конфигурации, который называется composer.json.

Основные задачи и возможности Composer:

1. Управление зависимостями: Composer позволяет определить, какие пакеты нужны для проекта, и автоматически загружает их вместе с необходимыми версиями. Например, если вашему проекту нужна библиотека для работы с базой данных или маршрутизацией, Composer установит их и все зависимости, которые требуются для их работы.

2. Автоматическое разрешение версий: Composer следит за совместимостью пакетов. При установке или обновлении зависимостей он проверяет, чтобы версии библиотек подходили друг другу и работали корректно в рамках вашего проекта.

3. Автозагрузка классов: Composer автоматически создает файл автозагрузки (autoload.php), который позволяет легко подключать и использовать классы из установленных пакетов без необходимости вручную прописывать require для каждого файла.

4. Поддержка семантического версионирования (SemVer): Composer поддерживает семантическое версионирование, что помогает управлять зависимостями, обновлять их до нужных версий или фиксировать определенные версии для обеспечения стабильности.

5. Платформа для пакетов (Packagist): Composer тесно интегрирован с официальным репозиторием PHP-пакетов под названием Packagist, где хранится большое количество библиотек и компонентов. Когда вы указываете в файле composer.json имя пакета, Composer автоматически находит его в Packagist и загружает.

`composer.json`: Настройка проекта

Чтобы начать использовать Composer в вашем проекте, все, что вам нужно, — это файл composer.json. Этот файл описывает зависимости вашего проекта и может также содержать другую метаинформацию. Обычно его следует размещать в корневом каталоге вашего проекта или репозитория системы управления версиями (VCS). Технически, Composer можно запускать в любом месте, но если вы хотите опубликовать пакет на Packagist.org, этот файл должен находиться в корне вашего репозитория VCS.

`require` ключ

Первое, что вы указываете в файле composer.json, — это ключ require. Вы сообщаете Composer, от каких пакетов зависит ваш проект.

{
    "require": {
        "monolog/monolog": "2.0.*"
    }
}

Как видно, ключ require принимает объект, который сопоставляет имена пакетов (например, monolog/monolog) с ограничениями версий (например, 1.0.*).

Composer использует эту информацию для поиска подходящих наборов файлов в "репозиториях" пакетов, которые вы регистрируете с помощью ключа repositories, или на Packagist.org, который является репозиторием пакетов по умолчанию. В приведенном выше примере, поскольку в файле composer.json не зарегистрирован другой репозиторий, предполагается, что пакет monolog/monolog зарегистрирован на Packagist.org.

Имена пакетов

Имя пакета состоит из имени поставщика (vendor) и имени проекта. Часто они будут идентичны, но имя поставщика существует для предотвращения конфликтов имен. Например, это позволяет двум разным людям создать библиотеку с названием json. Одна библиотека может называться igorw/json, а другая — seldaek/json.

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

Для первоначальной установки определённых зависимостей для вашего проекта, вам следует выполнить команду update.

php composer.phar update

Это заставляет Composer выполнить две задачи:

1. Он разрешает все зависимости, указанные в вашем файле composer.json, и записывает все пакеты и их точные версии в файл composer.lock, закрепляя проект за этими конкретными версиями. Вы должны добавить файл composer.lock в репозиторий вашего проекта, чтобы все, кто работает над проектом, использовали одни и те же версии зависимостей (подробнее об этом ниже). Это основная функция команды update.

2. Затем он автоматически выполняет команду install. Это приведет к загрузке файлов зависимостей в директорию vendor в вашем проекте. (Директория vendor — это принятое место для всего стороннего кода в проекте). В нашем примере выше вы получите исходные файлы Monolog в директории vendor/monolog/monolog/. Поскольку Monolog имеет зависимость от psr/log, файлы этого пакета также будут находиться внутри директории vendor/.

Добавьте файл composer.lock в систему контроля версий.

Добавление этого файла в систему контроля версий важно, потому что это гарантирует, что любой, кто настроит проект, будет использовать точно такие же версии зависимостей, которые используете вы. Ваш сервер непрерывной интеграции (CI), рабочие машины в продакшене, другие разработчики в вашей команде — всё и все будут работать с одинаковыми зависимостями, что снижает вероятность появления багов, затрагивающих только отдельные части развертываний. Даже если вы разрабатываете проект в одиночку, через шесть месяцев при переустановке проекта вы можете быть уверены, что установленные зависимости всё ещё работают, даже если с тех пор вышло много новых версий зависимостей.

Установка из файла composer.lock

Если в папке проекта уже есть файл composer.lock, это означает, что либо вы ранее запускали команду update, либо кто-то другой в проекте запускал эту команду и добавил файл composer.lock в репозиторий (что является хорошей практикой).

В любом случае, при наличии файла composer.lock команда install разрешает и устанавливает все зависимости, указанные в файле composer.json, но Composer использует точные версии, указанные в composer.lock, чтобы гарантировать, что версии пакетов будут одинаковыми для всех, кто работает над вашим проектом. В результате вы получите все зависимости, указанные в вашем файле composer.json, но они могут быть не самыми последними доступными версиями (некоторые из зависимостей, указанных в composer.lock, могли обновиться с момента его создания). Это сделано намеренно, чтобы проект не сломался из-за неожиданных изменений в зависимостях.

Поэтому, после получения новых изменений из вашего репозитория VCS, рекомендуется запустить команду composer install, чтобы убедиться, что папка vendor синхронизирована с вашим файлом composer.lock.

php composer.phar install

Composer по умолчанию обеспечивает воспроизводимость сборок. Это означает, что многократный запуск одной и той же команды создаст папку vendor/, содержащую идентичные файлы (за исключением их меток времени), включая файлы автозагрузчика. Это особенно полезно для сред, требующих строгих процессов проверки, а также для дистрибутивов Linux, которые стремятся упаковывать PHP-приложения безопасным и предсказуемым образом.

Обновление зависимостей до последних версий

Как упомянуто выше, файл composer.lock предотвращает автоматическое получение последних версий ваших зависимостей. Чтобы обновить зависимости до последних версий, используйте команду update. Эта команда загрузит последние совместимые версии (согласно вашему файлу composer.json) и обновит файл lock новыми версиями.

php composer.phar update

Примечание: Composer выведет предупреждение при выполнении команды install, если файл composer.lock не был обновлён после изменений в composer.json, которые могут повлиять на разрешение зависимостей.

Если вы хотите установить, обновить или удалить только одну зависимость, вы можете явно указать её в качестве аргумента:

php composer.phar update monolog/monolog [...]

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

Для библиотек, которые указывают информацию об автозагрузке, Composer генерирует файл vendor/autoload.php. Вы можете подключить этот файл и начать использовать классы, предоставляемые этими библиотеками, без дополнительной работы:

require __DIR__ . '/vendor/autoload.php';

$log = new Monolog\Logger('name');
$log->pushHandler(new Monolog\Handler\StreamHandler('app.log', Monolog\Logger::WARNING));
$log->warning('Foo');

Вы даже можете добавить свой собственный код в автозагрузчик, добавив поле autoload в файл composer.json:

{
    "autoload": {
        "psr-4": {"Acme\\": "src/"}
    }
}

Composer зарегистрирует автозагрузчик PSR-4 для пространства имен Acme.

Вы задаёте сопоставление пространств имен с каталогами. Каталог src должен находиться в корне вашего проекта, на одном уровне с каталогом vendor. Примером имени файла может быть src/Foo.php, содержащий класс Acme\Foo.

После добавления поля autoload, вам нужно повторно выполнить следующую команду:

php composer.phar dump-autoload

Эта команда пересоздаст файл vendor/autoload.php. См. раздел "dump-autoload" для получения дополнительной информации.

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

$loader = require __DIR__ . '/vendor/autoload.php';
$loader->addPsr4('Acme\\Test\\', __DIR__);

Помимо автозагрузки PSR-4, Composer также поддерживает автозагрузку по стандартам PSR-0, classmap и files.

Примечание: Composer предоставляет собственный автозагрузчик. Если вы не хотите использовать его, вы можете подключить файлы vendor/composer/autoload_*.php, которые возвращают ассоциативные массивы, что позволит вам настроить собственный автозагрузчик.

Composer Cheatsheet: Частые команды и их назначение

Установка Composer

Чтобы установить Composer на локальную машину:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');" php composer-setup.php
php -r "unlink('composer-setup.php');"

Это загрузит и установит Composer.

Инициализация проекта

composer init

Запускает пошаговый процесс создания файла composer.json, который описывает зависимости проекта, версию PHP и прочие параметры.

Установка пакетов

composer require <vendor>/<package>

Команда для установки новых пакетов в проект. Устанавливается последняя версия пакета и обновляется composer.json и composer.lock.

Пример:

composer require monolog/monolog
composer install

Используется для установки всех зависимостей, указанных в composer.lock. Если composer.lock не существует, зависимости будут установлены на основе composer.json, и файл composer.lock будет создан.

Обновление пакетов

composer update

Обновляет все зависимости до последних версий, разрешённых в composer.json. Также обновляет файл composer.lock.

composer update

composer update <vendor>/<package>

Обновляет только конкретный пакет до разрешённой версии.

Пример:

composer update symfony/console

Удаление пакетов

composer remove <vendor>/<package>

Удаляет пакет из проекта и обновляет файлы composer.json и composer.lock.

Пример:

composer remove monolog/monolog

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

composer dump-autoload

Регенерирует файлы автозагрузки для проекта. Используется, когда вы добавили новые классы вручную и хотите, чтобы они стали доступны через автозагрузчик Composer.

Просмотр информации о пакете

composer show

Выводит информацию о всех установленных пакетах.

composer show <vendor>/<package>

Показывает информацию о конкретном пакете.

Пример:

composer show monolog/monolog

Диагностика

composer diagnose

Проверяет конфигурацию проекта на предмет ошибок и проблем с установкой.

Глобальные пакеты

composer global require <vendor>/<package>

Устанавливает глобальные пакеты (например, инструменты для разработки).

Пример:

composer global require laravel/installer

composer global remove <vendor>/<package>

Удаляет глобальные пакеты.

Зависимости и конфликты

composer depends <vendor>/<package>

Показывает, какие пакеты зависят от указанного.

Пример:

composer depends monolog/monolog

composer prohibits <vendor>/<package>

Показывает, какие пакеты препятствуют установке указанного пакета.

Работа с версиями

^1.0: Устанавливает любую версию >=1.0 и <2.0.
\~1.2: Устанавливает любую версию >=1.2 и <1.3.
1.2.3: Устанавливает конкретную версию.
*: Любая версия.

Автоматическое обновление Composer

composer self-update

Обновляет Composer до последней версии.

composer self-update --rollback

Откатывает обновление Composer к предыдущей версии.

Другие полезные команды

composer outdated

Показывает список установленных пакетов, для которых доступны новые версии.

composer clear-cache

Очищает локальный кэш Composer (полезно при проблемах с установкой или обновлением пакетов).

composer clear-cache

DEV && PROD

В Composer зависимости делятся на dev (для разработки) и production (для боевого окружения). Это полезно, потому что dev-зависимости нужны только для разработки и тестирования, а не на продакшене.

Пример composer.json

{
  "require": {
    "monolog/monolog": "^2.0"  // продакшн зависимость
  },
  "require-dev": {
    "phpunit/phpunit": "^9.0"  // dev зависимость
  }
}

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

1. Продакшн зависимость:

composer require monolog/monolog

Эта команда добавляет зависимость в секцию require в composer.json.

2. Dev зависимость:

composer require phpunit/phpunit --dev

Эта команда добавляет зависимость в секцию require-dev.

Установка зависимостей при деплое

Для установки только боевых зависимостей (без dev-зависимостей):

composer install --no-dev

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

1. Чтобы обновить все зависимости (включая dev):

composer update

2. Чтобы обновить только продакшн зависимости:

composer update --no-dev

3. Чтобы обновить конкретную зависимость:

composer update monolog/monolog

Composer и Bitrix Framework

:::warning Есть 2 варианта использования. (Даже 3). Но самое оптимальное — не трогать composer битрикс и использовать свой, подтянув autoload в init. Но если делать как надо, то вот инструкция с объединением

:::

По умолчанию система ожидает увидеть ваш файл composer.json в папке bitrix, но НУЖНО РАЗМЕСТИТЬ В local/composer. В этом случае нужно указать путь до файла в .settings.php, чтобы его конфигурация могла быть использована в продукте.

:::warning Если вы начали использовать Composer. Вам нужно сообщить об этом менеджеру. Вы должны сказать, что вот используется Composer и нужно закрыть для доступа на уровне DevOps доступ к папке /local/composer целиком.

:::

:::tip Не забудьте правило .gitignore на local/composer. А так же добавить 2 правила исключения для файлов: composer.json composer.lock.

Так же, если на вашем проекте используются миграции и проект уже перенес на ПРОД, то необходимо сделать миграцию на настройки .settings через модуль sprint.migrations или описать инструкцию, как это добавить на проде.

:::

Файл .settings.php:

<?php
return [
    'composer' => [
        'value' => ['config_path' => '/path/to/your/composer.json']
    ],
    // ...
];

В нем необходимо подключить наш файл с зависимостями bitrix/composer-bx.json с помощью плагина Composer Merge Plugin. В минимальном виде ваш composer.json должен содержать вызов плагина и подключение нашей конфигурации.

Файл composer.json (можно скопировать из bitrix/composer.json.example):

{
    "require": {
        "wikimedia/composer-merge-plugin": "dev-master"
    },
    "extra": {
        "merge-plugin": {
            "require": [
                "/path/to/bitrix/composer-bx.json"
            ]
        }
    }
}

Вместо /path/to/bitrix/ вам нужно указать реальный путь до папки bitrix.

К этому вы можете добавить свои зависимости и настройки. Например, чтобы явно задать путь до папки vendor (по умолчанию она будет там же, где файл composer.json), используйте директиву "vendor-dir".

После описания своей конфигурации останется установить библиотеки:

composer install

Теперь вы можете использовать преимущества composer в своем проекте, подключая файл vendor/autoload.php. При использовании CLI-команд он будет подключен автоматически.

Composer

Основные задачи и возможности Composer:

composer.json: Настройка проекта

require ключ

Имена пакетов

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

Добавьте файл composer.lock в систему контроля версий.

Установка из файла composer.lock

Обновление зависимостей до последних версий

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

Composer Cheatsheet: Частые команды и их назначение

Установка Composer

Инициализация проекта

Установка пакетов

Пример:

Обновление пакетов

Пример:

Удаление пакетов

Пример:

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

Просмотр информации о пакете

Пример:

Диагностика

Глобальные пакеты

Пример:

Зависимости и конфликты

Пример:

Работа с версиями

Автоматическое обновление Composer

Другие полезные команды

DEV && PROD

Пример composer.json

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

Установка зависимостей при деплое

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

Composer и Bitrix Framework

Файл .settings.php:

`composer.json`: Настройка проекта

`require` ключ