Что такое require в composer.json?

Что такое require в composer.json

В файле composer.json, секция require — это основной и обязательный элемент, который определяет зависимости (dependencies) вашего PHP-проекта. Проще говоря, здесь вы указываете, какие внешние библиотеки (пакеты) и их версии необходимы для работы вашего приложения.

Ключевая роль секции require

Секция require выполняет несколько критически важных функций:

1. Декларация зависимостей: Вы объявляете, без чего ваш проект не сможет функционировать. Например, фреймворк Laravel, ORM Doctrine или библиотека для работы с HTTP Guzzle.
2. Управление версиями: Вы задаёте ограничения на версии (version constraints), что позволяет контролировать, какие именно версии пакетов будут установлены. Это основа стабильности и предсказуемости.
3. Разрешение зависимостей: Composer анализирует эту секцию, находит все указанные пакеты, а также их зависимости (transitive dependencies), и создаёт непротиворечивый набор версий, который можно установить. Результат фиксируется в файле composer.lock.

Структура и синтаксис

Секция require является ассоциативным массивом в формате JSON, где ключ — это имя пакета, а значение — строка с ограничением версии.

{
    "require": {
        "vendor/package-name": "version-constraint",
        "monolog/monolog": "^2.0",
        "guzzlehttp/guzzle": "~7.4.0",
        "php": ">=8.1",
        "ext-json": "*"
    }
}

Типы зависимостей в require

В секцию require можно добавлять не только библиотеки из Packagist:

• Библиотеки/PHP-пакеты: Основной тип (например, "symfony/http-foundation": "^6.0").
• Версия PHP: Критически важное ограничение. Composer проверит, соответствует ли среда выполнения заданным критериям.

  "require": {
      "php": "^8.1"
  }
  

• Расширения PHP (ext-*): Требования к конкретным расширениям PHP.

  "require": {
      "ext-mbstring": "*",
      "ext-pdo": ">=7.4"
  }
  

• Системные библиотеки (lib-*): Зависимости от системных компонентов, например, определённой версии lib-curl.

  "require": {
      "lib-curl": "*"
  }
  

Ограничения версий (Version Constraints)

Правильное указание версий — это искусство баланса между стабильностью и получением обновлений. Основные форматы:

• Точная версия: "1.2.3" — только эта версия.
• Диапазон: ">=1.0 <2.0" или "1.0.0 - 1.5.0".
• Волновой диапазон (Tilde) ~: "~1.2.3" означает >=1.2.3 <1.3.0. Обновления только для минорной версии (если указаны три части) или патча (если две: ~1.2 -> >=1.2.0 <2.0.0).
• Оператор совместимости (Caret) ^: Наиболее популярный. "^1.2.3" означает >=1.2.3 <2.0.0. Позволяет обновлять до следующей мажорной версии, но не ломает обратную совместимость (согласно SemVer).
• Dev-версии и ветки: Можно требовать конкретную ветку ("dev-main") или тег ("dev-version-1.0"), но это практикуется в основном в require-dev.

require vs require-dev

Важно не путать с соседней секцией require-dev:

• require: Пакеты, необходимые всегда (в production, staging, development). Это каркас вашего приложения.
• require-dev: Пакеты, необходимые только для разработки и тестирования (например, PHPUnit, PHPStan, Faker). Они не попадут в production-сборку, если установка выполняется с флагом --no-dev.

Практический пример и процесс

Представьте файл composer.json:

{
    "name": "acme/my-project",
    "require": {
        "php": "^8.1",
        "laravel/framework": "^10.0",
        "guzzlehttp/guzzle": "^7.0"
    }
}

Когда вы выполняете команду composer install, происходит следующее:

1. Composer читает секцию require.
2. Обращается к репозиторию Packagist для поиска пакетов laravel/framework и guzzlehttp/guzzle.
3. Находит последние версии, соответствующие ограничениям ^10.0 и ^7.0.
4. Рекурсивно анализирует их секции require, формируя полное дерево зависимостей.
5. Разрешает возможные конфликты версий (если две библиотеки требуют несовместимые версии третьей).
6. Скачивает все разрешённые пакеты в папку vendor/.
7. Создаёт (или обновляет) composer.lock — точную карту установленных версий. Этот файл должен быть закоммичен в VCS для гарантии идентичных установок у всех разработчиков и на серверах.

Важные выводы

• require — это декларация "что нужно". В отличие от composer.lock, который фиксирует "что точно установлено".
• Изменения в require (добавление, удаление пакета, изменение версии) требуют запуска composer update (для обновления composer.lock и vendor/) или composer require vendor/package (что сделает это автоматически).
• Игнорирование секции require или некорректное указание версий — прямая дорога к "работает у меня на машине" и проблемам при деплое.

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