composer lock что это такое
PHP Profi
Квест → Как хакнуть форму
Composer является стандартом де-факто для управления зависимостями в PHP. Он прост, эффективен и уже стал вездесущ.
Каждый знает, что при использовании Composer вы просто создаёте файл composer.json со списком зависимостей и их версий, а после запускаете composer install и всё готово.
Что ж, пока вы не делаете код-ревью каждой новой версии используемых вами зависимостей, и их зависимостей, и зависимостей зависимостей. и т.д. и т.п., то остаётся высокая вероятность того, что какой-нибудь закравшийся баг поломает ваше приложение. В конце концов, все мы люди.
Install или Update?
Команда composer install делает следующее:
Команда composer update :
В любом случае, после запуска любой из команд вы длжны закоммитить composer.lock в вашу систему контроля версий, чтобы быть уверенными, что вся команда имеет одну и ту же картину.
Есть одно исключение из правила. В том случае, если вы устанавливаете что-то вроеде Zend Framework 2 Skeleton App, зависимости должны быть обновлены как только вы установили подобный каркас. Это потому, что Skeleton App является эдаким мета-приложением (карксом-примером). Соответственно в этом случае вы захотите «подтянуть» последние версии зависимостей, которые станут отправной точкой для начала разработки. Поэтому composer.lock не коммитится в репозитории подобных мета-приложений.
Выкладка (deploy)
Наличие файла composer.lock также обеспечивает консистентность между кластерами серверов, если вы запускаете Composer отдельно на каждой машине. Это позволяет вам развернуть новые ноды(машины) неделями или месяцами позже, не беспокоясь о несовпадении версий зависимостей.
Заключение
Composer для самых маленьких
Когда я первый раз разбирался с composer, я набросал для себя маленькую шпаргалку и теперь, спустя некоторое время представляю её на суд общественности в несколько доработанном виде.
Данная публикация актуальная для тех, кто в первый раз столкнулся с незаменимым менеджером пакетов для PHP.
Итак, Composer — менеджер пакетов для PHP.
Для чего нужен Composer и простейший пример его использования
Возьмем для примера этот проект
Если в двух словах: то это набор скриптов для работы в VK API
Соответственно, для работы этих скриптов нужно несколько библиотек
Библиотеки перечислены в файле composer.json — ключевой файл при работе с composer
В этом проекте используется 5 библиотек. Соответственно, если разработчик решит опубликовать этот проект на github, то ему достаточно закинуть в репу саму папку со скриптами и составить composer.json, в котором будут описаны библиотеки, необходимые для работы этого проекта. Простота очевидна: в репу не нужно вслед за файлами прицепом тащить все нужные библиотеки. Занимает меньше места, проще распространять проект.
В папке scripts лежат непосредственно скрипты проекта, для работы которых и требуются эти 5 пакетов.
Запускаем установку пакетов:
После установки появляется папка vendor, куда складываются установленные пакеты и формируется файл autoload.php
Этот файл подключаем к проекту и всё — библиотеки подключены, можно спокойно с ними работать.
Простота очевидна: не нужно скачивать и подключать библиотеки и их зависимости самостоятельно, composer всё сделает за Вас. И вся эта пачка подключается одним единственным файлом autoload.php
Все пакеты, которые лежат в vendor, добавляются в автозагрузчик. При этом composer опирается на файлы composer.json, которые должны быть у каждого пакета. Формирование composer.json пакета — это задача разработчика пакета, от потребителя пакета требуется лишь описать в composer.json проекта, какие пакеты нужно подключить.
Это пример composer.json проекта:
Это пример composer.json пакета:
В секции require прописана зависимость этого пакета — библиотека guzzle http, необходимая для работы библиотеки getjump/vk. В данном случае, т.е. с точки зрения потребителя пакетов, всевозможные зависимости пакетов — это не наша «забота», с зависимостями composer разберётся сам.
Пространство имён пакета прописано в секции autoload
getjump\\Vk\\ — наименование пространства имён
src/getjump/Vk/ — директория, в которой лежат файлы с классами пакета
Работа с этой библиотекой в проекте:
Core и Friends — это классы библиотеки, которые разложены и прописаны в папке src в соответствии со стандартом PSR-4. Опять же формирование структуры пакета — это работа создателя пакета.
Нам, как потребителю пакета, достаточно прописать в наш проект
include ‘../vendor/autoload.php’;
и все эти классы и пространства имён будут отлично работать.
При этом нам не нужно заморачиваться и писать автозагрузчик. Composer это сделает сам при выполнении команды install.
Установка
Установка Composer глобально
1) Для начала нужно что бы путь к директории с интерпретатором PHP был прописан в переменной окружения path.
Проверим, так ли это:
php –version
Далее нас будет интересовать переменная path:
Вписываем путь к интерпретатору
*С давних времён у меня на компьютере лежит сборка xampp, сама сборка здесь нафиг не нужна, а вот интерпретатор с неё вполне подойдёт (версия PHP – 5.6).
3) Добавим в переменную окружения path путь к composer.bat, например для D:\bin должно получиться:
Дополнительно можно добавить в path
D:\Users\%userName%\AppData\Roaming\Composer\vendor\bin\
для того, что-бы было удобнее использовать инструменты, глобально установленные через Composer.
(У меня папка Users располагается на диске D, а на C создан симлинк на неё).
Всё, composer установлен и полностью готов к работе.
Ещё: при установке можно словить ошибку
[RuntimeException]
The APPDATA or COMPOSER_HOME environment variable must be set for composer to run correctly
Решение нашлось здесь github.com/composer/composer/issues/2033
Добавляем переменную APPDATA со значением D:\Users\GSU\AppData\Roaming
Установка Composer локально
Отличия глобальной и локальной установки
Команды запускаются по разному при локальной и глобальной установках:
Например:
Локально: php composer.phar require silex/silex
1.1
Глобально: composer require silex/silex
При глобальной установке этот файл не нужен. Composer запускается при любой текущей директории.
Команды
Синтаксис composer.json
Именование пакетов и варианты описания пакетов
Имя пакета состоит из двух частей разделёных косой чертой: названия поставщика (vendor name) и названия библиотеки.
Если пакет оформлен в соответствии со стандартом PSR-4, но опубликован не на packagist.org, а на github, то вместо версии пакета нужно прописать ветку и репозиторий для этого пакета:
Пример подключения библиотеки, которая лежит на github, но при этом не оформлена по стандарту PSR-4, а представляет из себя обыкновенное нагромождение файлов с классами и функциями.
Pqr/superlib — эта та самая «неправильная» библиотека.
В секции repositories для неё пишем такую конструкцию
Ключевой момент — секция autoload, здесь указываем нужные нам файлы с классами и функциями.
Структура библиотеки:
Не игнорьте composer.lock
install vs update
Какой же этот Composer долгий… И памяти жрёт при обновлении…
Через какое-то время после очередного деплоймента продакшн снова фатально падает. Какого.
Composer — одна из причин, по которой PHP сегодня именно такой. Популярный, прогрессивный и удобный. Именно поэтому мы в RUVENTS считаем понимание принципов работы менеджера зависимостей одним из ключевых навыков PHP-программиста.
Фиксация зависимостей
При работе с зависимостями нам хотелось бы достичь следующих результатов:
Для достижения этих целей необходим механизм, который в момент фиксации изменений будет запоминать состояние зависимостей как часть состояния проекта. Назовем это фиксацией зависимостей.
Самая простая реализация такого механизма — lock-файл с информацией об установленных зависимостях. Файл должен храниться в репозитории и позволять однозначно воспроизводить на любой другой площадке набор пакетов, использованных программистом при разработке.
А что там у Composer
В Composer lock-файл называется composer.lock и располагается в корне проекта. Чтобы понять, как он генерируется и используется, разберем механизм работы двух команд менеджера.
composer update
Для каждого заявленного в проекте пакета менеджер находит его источник, считывает информацию о версиях и зависимостях, а затем рекурсивно повторяет то же самое для зависимостей пакета, чтобы получить полное дерево. После этого Composer разрешает зависимости с учетом версионных правил, объявленных во всех собранных composer.json файлах.
Информация о пакете, рекомендованном к установке, имеет следующий вид:
Плоский массив таких объектов будет записан в формате JSON в злополучный файл composer.lock по завершении команды. Это и есть фиксация зависимостей в Composer.
После всех этих ресурсоёмких операций менеджер сопоставляет разрешенные зависимости с уже имеющимися пакетами в папке vendor/ и устраняет несоответствия: удаляет устаревшие и ненужные пакеты, скачивает (или подтягивает из кэша) новые и добавленные.
composer install
Задача команды composer install — установить зафиксированные зависимости проекта.
Если composer.lock отсутствует, команда выполняет те же действия, что и composer update (включая создание lock-файла).
Итак, composer install использует зафиксированные в composer.lock зависимости как готовую инструкцию для установки/обновления, а composer update игнорирует этот файл и производит установку/обновление с нуля.
Может быть всё-таки заигнорить?
Нет. Игнорировать можно девушку или парня, чтобы подогреть интерес к себе (только не переборщите!). composer.lock же, напротив, сразу готов с вами сотрудничать.
Не храня lock-файл в репозитории, вы отказываетесь от механизма фиксации зависимостей. Несмотря на то, что composer.lock будет в любом случае сгенерирован, Composer не сможет гарантировать, что установленные пакеты будут иметь те же версии, что при разработке.
Почему упал продакшн?
Как вы теперь поняли, история из предисловия (основанная на реальных событиях) демонстрирует ошибочную цепочку рассуждений. И вот каким образом она может привести к беде.
Допустим, есть composer.json следующего содержания:
Как с этим жить
Composer lock что это такое
Примечание: для простоты в этом ознакомлении будем считать, что Вы выполнили локальную установку Composer
composer.json : Настройка проекта
Чтобы начать использовать Composer в Вашем проекте, всё, что Вам нужно это composer.json файл. Этот файл описывает зависимости Вашего проекта и может содержать также другие метаданные.
Как Вы можете видеть require принимает объект состоящий из имени пакета (например monolog/monolog ) и версии пакета (например 1.0.* ).
Ограничения для версий можно указать несколькими способами, читайте версии для получения более подробной информации по этой теме.
По умолчанию только стабильные релизы принимаются во внимание. Если бы Вы хотели бы также получить зависимости RC, beta, alpha или dev версий, Вы можете это сделать с помощью флагов стабильности (stability flags). Чтобы применить это для всех пакетов, вместо того чтобы делать это для каждой зависимости, Вы также можете использовать настройку минимальная стабильность (minimum-stability).
Чтобы установить зависимости для Вашего проекта просто запустите команду install
Вы заметите, что команда install также создала файл composer.lock
composer.lock фиксирует Ваши приложения (наряду с composer.json ) в системе контроля версий.
Это важно потому, что команда ‘install’ проверяет присутствует ли файл блокировки, и если это так, он загружает указанные там версии (независимо от того, что говорит composer.json ).
Это означает, что любой, кто настраивает проект, будет загружать точно такие же версии зависимостей. Ваш CI сервер, рабочая машина, другие разработчики в Вашей команде, все они и всё работает на одних и тех же зависимостях, что снижает потенциал для ошибок, затрагивающих только некоторые части развертывания. Даже если Вы разрабатываете самостоятельно, через шесть месяцев при переустановке проекта, Вы можете быть уверены, что установленные зависимости по-прежнему работают даже если зависимости выпустили много новых версий с тех пор.
Примечание: Composer отобразит предупреждение при выполнении команды install если composer.lock и composer.json не синхронизированы.
Если Вы хотите установить или обновить только одну зависимость, Вы можете сделать это следующим образом:
Packagist является главным репозиторием (хранилищем) Composer. Репозиторий Composer это основной источник пакетов: место, откуда Вы можете получить различные пакеты. Packagist стремится быть центральным репозиторием который используют все. Это означает, что можно автоматически затребовать require для любого пакета который доступен здесь.
Если Вы перейдёте на веб-сайт Packagist (packagist.org), здесь Вы можете просматривать и искать пакеты.
Любой проект с открытым кодом используемый с Composer рекомендуется публиковать на Packagist. Библиотекам не обязательно нужно находиться на Packagist чтобы использовать Composer, но это позволяет более быстро обнаруживать их и пробовать их другими разработчиками.
Это делает библиотеку очень простой в использовании третьей стороной. Например: Если Ваш проект зависит от Monolog, Вы можете просто начать использовать классы из него, и они будут видны.
Включая этот файл, он также будет возвращать экземпляр автозагрузчика, так что Вы можете хранить его возвращаемое значение в переменной и добавлять больше пространств имен. Это может быть полезно для автоматической загрузки классов в наборе тестов, например.
В дополнение к PSR-4 автозагрузке Composer также поддерживает PSR-0, classmap и файловую автозагрузку. Смотрите раздел autoload (автозагрузка) для получения большей информации.
Примечание: Composer предоставляет свой собственный автозагрузчик. Если Вы не хотите использовать его одного, Вы можете просто включить файлы vendor/composer/autoload_*.php которые возвращают ассоциативные массивы, позволяя Вам настроить свой собственный автозагрузчик.
21 совет по эффективному использованию Composer
Совет № 1: читайте документацию
Я серьёзно. Документация у него замечательная, и несколько часов чтения сэкономят вам кучу времени в долгосрочной перспективе. Вы удивитесь, как много всего умеет делать Composer.
Совет № 2: различайте проект и библиотеку
Важно знать, что вы создаёте — проект или библиотеку. Каждый из вариантов требует своего набора методик.
Проект обычно представляет собой приложение, зависящее от нескольких библиотек. Обычно он не используется несколько раз (никакому другому проекту он не понадобится в качестве зависимости). Характерные примеры: сайт интернет-магазина, система поддержки пользователей и т. д.
Дальше в советах я буду переключаться между библиотекой и проектом.
Совет № 3: используйте для приложения конкретные версии зависимостей
Обновляйте зависимости обдуманно, а не импульсивно. Подробнее об этом мы поговорим в одном из следующих советов.
Возможно, это кажется чрезмерным, но внимание к версиям зависимостей не даст вашим коллегам неосмотрительно обновить все зависимости при добавлении в проект новой библиотеки (которую вы могли пропустить при ревизии кода).
Совет № 4: для зависимостей библиотек используйте диапазоны версий
Если вы делаете библиотеку, то определяйте самый возможный диапазон версий. Если создаёте библиотеку, использующую библиотеку symfony/yaml для YAML-разбора, то запрашивайте её так: «symfony/yaml»: «^3.0 || ^4.0»
Тогда ваша библиотека сможет использовать symfony/yaml из любых версий Symfony с 3.x по 4.x. Это важно, поскольку данное ограничение распространяется и на приложение, которое обращается к вашей библиотеке.
Если есть две библиотеки с конфликтующими требованиями (одной, к примеру, нужна
3.2.0), то будет сбой при установке.
Совет № 5: в приложениях нужно коммитить composer.lock в Git
Если вы создаёте проект, то нужно коммитить composer.lock в Git. Тогда все — вы, ваши коллеги, ваш CI-сервер и рабочий сервер — будут использовать приложение с одинаковыми версиями зависимостей.
На первый взгляд этот совет кажется излишним. Вы уже выбрали конкретную версию, как в совете № 3. Но ещё существуют зависимости ваших зависимостей, которые не связаны этими ограничениями (например, symfony/console зависит от symfony/polyfill-mbstring ). Так что без коммита composer.lock вы не получите такой же набор зависимостей.
Если вы создаёте библиотеку (назовём её acme/my-library ), то не нужно коммитить файл composer.lock. Это никак не влияет на проекты, использующие вашу библиотеку.
Если хотите быть уверены в совместимости библиотеки с разными версиями её зависимостей, читайте следующий совет!
Совет № 7: запускайте сборки Travis CI с разными версиями зависимостей
Совет относится только к библиотекам (потому что для приложений вы используете конкретные версии).
Если вы собираете open-source библиотеку, то, вероятно, запускаете сборки с помощью Travis CI. По умолчанию Composer устанавливает последние возможные версии зависимостей, допускаемые ограничениями в composer.json. Это означает, что для ограничения зависимости ^3.0 || ^4.0 сборка всегда будет использовать последнюю версию релиза v4. И поскольку версия 3.0 никогда не тестировалась, библиотека может оказаться несовместимой с ней, что опечалит пользователей.
Можете посмотреть её в работе на примере моей библиотеки mhujer/fio-api-php и матричной сборки Travis CI.
Хотя это решение позволит выловить большинство несовместимостей, помните, что между старшей и младшей версиями существует много комбинаций зависимостей. И они могут быть несовместимы.
Совет № 8: сортируйте пакеты в require и require-dev по имени
Хорошая привычка — держать пакеты в require и require-dev отсортированными по имени. Это поможет пресекать ненужные конфликты слияния при перебазировании ветки. Потому что если вы в двух ветках добавляете пакет в конце списка, то конфликты слияния будут возникать каждый раз.
Вручную это делать нудно, так что лучше сконфигурировать в composer.json:
Когда вы в следующий раз затребуете ( require ) новый пакет, он будет добавлен в правильное место (не в конец).
Совет № 9: не пытайтесь объединять composer.lock при перебазировании или слиянии
Если вы добавили в composer.json новую зависимость (и composer.lock) и перед слиянием ветки в мастер была добавлена другая зависимость, вам нужно перебазировать ветку. И вы получите в composer.lock конфликт слияния.
Никогда не пытайтесь разрешить его вручную, потому что файл composer.lock содержит хеш зависимостей, определённых в composer.json. Так что, если даже вы разрешите конфликт, получится некорректный lock-файл.
Можете решить проблему с помощью кратковременных веток фич (feature branches), как предлагается в Trunk Based Development (это нужно делать в любом случае). Если у вас есть правильно объединённая краткосрочная ветка, риск конфликта слияния в composer.lock минимален. Даже можете создать ветку только для добавления зависимости и сразу объединить её.
Совет № 10: помните о разнице между require и require-dev
Пакеты, необходимые для разработки приложения или библиотеки, должны быть определены в require-dev (например, PHPUnit, PHP_CodeSniffer, PHPStan).
Совет № 11: обновляйте зависимости безопасно
Полагаю, вы согласны с утверждением, что зависимости нужно регулярно обновлять. И я советую делать обновление зависимостей прозрачно и продуманно, а не по мере какой-то другой работы. Если вы что-то рефакторите и в то же время обновляете какие-то библиотеки, то не сможете сказать, чем сломано приложение, рефакторингом или обновлением.
Для каждой устаревшей зависимости придерживайтесь плана:
Или можете использовать шаблон для обновления всех зависимостей из определённого пространства имён:
Знаю, всё это выглядит утомительным, но наверняка вы обновляете зависимости по случаю, так что лучше перестраховаться.
Можно лишь в одном облегчить себе работу: разом обновлять все зависимости require-dev (если они не требуют изменений в коде, иначе предлагаю использовать отдельные ветки для упрощения ревизии кода).
Совет № 12: можете определять в composer.json другие типы зависимостей
Помимо определения библиотек в качестве зависимостей, вы также можете определять там и другие вещи.
Например, какие версии PHP поддерживает приложение/библиотека:
Или какие расширения необходимы приложению/библиотеке. Это очень полезно, если пытаешься поместить приложение в контейнер или если твой новый коллега впервые настраивает приложение.
Используйте * для версий расширений, потому что они могут быть несогласованными.
Совет № 13: проверяйте composer.json в ходе CI-сборки
composer.json и composer.lock должны быть всегда синхронизированы. Поэтому целесообразно автоматически проверять их синхронизированность. Просто добавьте этот механизм в свой скрипт сборки:
Совет № 14: используйте Composer-плагин в PHPStorm
Существует composer.json-плагин для PHPStorm. Он добавляет автокомплит и ряд проверок при ручном изменении composer.json.
Если вы используете другую IDE (или только редактор кода), можете настроить проверку его JSON-схемы.
Совет № 15: определяйте в composer.json рабочие версии PHP
Если вы, как и я, любите иногда локально запускать предварительные релизы версий PHP, то рискуете обновить зависимости до версий, не работающих в продакшене. Сейчас я использую PHP 7.2.0, т. е. могу устанавливать библиотеки, которые не будут работать на 7.1. А поскольку продакшен использует 7.1, установка завершится сбоем.
Но переживать не нужно, есть лёгкое решение. Просто определите рабочие версии PHP в разделе config файла composer.json:
Совет № 16: используйте приватные пакеты из Gitlab
Рекомендую выбирать vcs в качестве типа репозитория, и Composer должен определить правильный способ извлечения пакетов. Например, если вы добавляете форк с GitHub, он будет использовать свой API для скачивания zip-файла вместо клонирования всего репозитория.
Но с приватной установкой с Gitlab несколько сложнее. Если вы используете vcs в качестве типа репозитория, Composer определит его как Gitlab-установку и попытается скачать пакет через API. Для этого потребуется API-ключ. Я не хотел его настраивать, поэтому сделал так (моя система использует SSH для клонирования).
Сначала определил репозиторий типа git :
А затем использовал пакет, как это обычно делается:
Совет № 17: как временно использовать ветку из форка с исправлением бага
Если вы нашли баг в публичной библиотеке и исправили его в своём форке на GitHub, то вам нужно установить библиотеку из своего репозитория, а не из официального (пока исправление не будет объединено и не появится исправленный релиз).
Это легко можно сделать с помощью inline aliasing:
Можете локально протестировать своё исправление, прежде чем загружать его, используя path в качестве типа репозитория.
Совет № 18: установите prestissimo для ускорения установки пакетов
Composer-плагин hirak/prestissimo ускоряет установку зависимостей посредством параллельного скачивания.
Достаточно установить его один раз глобально, и он будет автоматически работать для всех проектов:
composer global require hirak/prestissimo
Совет № 19: если не уверены, протестируйте свои версионные ограничения
Написание корректных версионных ограничений иногда становится непростой задачей после прочтения документации.
Совет № 20: используйте в продакшене авторитарную карту классов (class map)
Сгенерируйте в продакшене авторитарную карту классов. Это ускорит загрузку классов благодаря включению в карту всего необходимого и пропуску любых проверок файловой системы.
Можете делать это в рамках вашей рабочей сборки:
Совет № 21: для тестирования сконфигурируйте autoload-dev
Вам не нужно включать тестовые файлы в рабочую карту классов (из-за размера файла и потребления памяти). Это можно сделать с помощью конфигурирования autoload-dev (аналогично autoload ):