Это статья, переведенная сообществом, и перевод завершен. Для получения дополнительной информации, пожалуйста, нажмитеВведение в совместный перевод.
Хотя большинство PHP-разработчиков знают, как использовать
Composer, но не все из них используют его эффективно или наилучшим образом. Поэтому я решил обобщить несколько вещей, которые важны для моего повседневного рабочего процесса. Идея большинства техник состоит в том,"Играть безопасно", что означает, что если есть больше способов сделать что-то, я буду использовать наименее подверженный ошибкам.
Совет №1: читайте документацию
Я был серьезен. официальная документацияОчень хорошо написано, всего несколько часов чтения сейчас сэкономят вам много времени в будущем. Вы будете удивлены, насколько универсален Composer.Совет № 2: распознайте разницу между «проектами» и «библиотеками»
Важно знать, создаете ли вы «проект» или «библиотеку». Существует огромная разница между ними в использовании.
Библиотека — это повторно используемый пакет, который необходимо добавить в качестве зависимости, например.symfony/symfony, doctrine/orm или elasticsearch/elasticsearch.
Типичный проект — это приложение, которое зависит от нескольких библиотек. Как правило, его нельзя использовать повторно (другие проекты не нуждаются в зависимости). Типичными примерами являются такие типы приложений, как веб-сайты электронной коммерции, системы обслуживания клиентов и т. д.
В совете ниже я более подробно объясню разницу между библиотекой и проектом.
Совет № 3: Используйте указанную версию зависимостей для вашего приложения
При создании приложения зависимости должны быть определены с максимально четким номером версии. Если вам нужно проанализировать файл YAML, вы должны начать с"symfony/yaml": "4.0.2"Такие формы определяют зависимости. даже если зависимая библиотека следуетСемантическое управление версиямиспецификации, а также нарушает обратную совместимость из-за различий в дополнительных номерах версий и редакций. Например, используя что-то вроде"symfony/symfony": "^3.1", может существовать в
3.2 устаревший материал, и это не позволит вашему приложению проходить тесты с этой версией. Или, может быть, в PHP_CodeSniffer есть исправленная ошибка, и код обнаруживает новые проблемы с форматированием, что снова приводит к плохим сборкам.Обновления зависимостей должны быть осторожными и не иметь большой удачи. Ниже приведен совет, который объясняет это более подробно.
Звучит паникёрски, но внимание к этому моменту предотвратит случайное обновление всех зависимостей вашими партнёрами при добавлении новых библиотек в проект (что может быть упущено при просмотре кода).
Совет № 4. Используйте диапазоны версий для зависимостей библиотек
При создании библиотеки вы должны определить максимально возможный диапазон доступных версий. Например, чтобы создать библиотеку, использоватьsymfony/yamlБиблиотека выполняет парсинг YAML, это должно быть написано так:"symfony/yaml": "^3.0 || ^4.0"
symfony/yaml. Это важно, потому что это ограничение версии передается приложениям, использующим библиотеку. Если есть конфликтующие запросы от двух библиотек, например, одна запрашивает~3.1.0, другой требует~3.2.0, установка завершится ошибкой.
Совет № 5: разрабатывайте приложения для отправкиcomposer.lockфайл в репозиторий git
созданный пункт, обязательно поставьтеcomposer.lockФайл привязан к git. Это гарантирует, что все — вы, ваши партнеры, ваш CI-сервер и ваш рабочий сервер — будут запускать приложение с одинаковыми версиями зависимостей. На первый взгляд это кажется излишним, но в совете №3 упоминалось ограничение использования явных номеров версий. Это не избыточно, имейте в виду, что зависимости используемых вами зависимостей не связаны этими ограничениями (например,symfony/consoleтакже зависит отsymfony/polyfill-mbstring). Если не отправленоcomposer.lockфайл, вы не получите ту же версию коллекции зависимостей.
Совет № 6: Библиотека разработки должнаcomposer.lockфайл добавлен в.gitignoreв файле
Создайтебиблиотека(например, называетсяacme/my-library), что не должноcomposer.lockФайл зафиксирован в репозитории git. Этот файл полезен для проектов, использующих библиотеку.не будет никакого эффекта. Предположениеacme/my-library использовать monolog/monologкак зависимость. Вы зафиксировали в репозиторииcomposer.lock, развиватьacme/my-libraryнаверное все пользуются
Старая версия Монолога. После завершения разработки библиотеки, если библиотека используется в реальном проекте, может быть установлена новая версия Monolog, которая на данный момент будет несовместима с библиотекой. Но вы никогда раньше не замечали проблемы с совместимостью из-за этогоcomposer.lock!Поэтому лучший способ борьбы сcomposer.lock добавить в .gitignoreфайл, что позволяет избежать проблем, вызванных случайной фиксацией его в репозиторий.
Если вы также хотите убедиться, что библиотека остается совместимой с различными версиями ее зависимостей, читайте следующий совет!
Совет № 7: Travis CI создает разные версии зависимостей
Текущий совет относится только к библиотекам (конкретные номера версий для приложений).
Если вы создаете библиотеку с открытым исходным кодом, скорее всего, вы будете использовать Travis CI для запуска процесса сборки.
По умолчанию вcomposer.jsonУстановка Composer установит последнюю возможную версию зависимостей, если позволяют ограничения файла. Это означает, что для^3.0 || ^4.0С таким ограничением зависимости установка сборки всегда использует последний пакет выпуска v4. А версию 3.0 тестировать вообще не будут, встроенная библиотека может быть несовместима с этой версией, и ваши пользователи будут плакать. К счастью, composer предоставляет переключатель для установки зависимостей с низкими версиями.
--prefer-lowest(следует использовать--prefer-stable, что предотвращает установку нестабильных версий). загружено.travis.ymlКонфигурация аналогична следующему формату:language: php
php:
- 7.1
- 7.2
env:
matrix:
- PREFER_LOWEST="--prefer-lowest --prefer-stable"
- PREFER_LOWEST=""
before_script:
- composer update $PREFER_LOWEST
script:
- composer ci
Подробности смотрите в кодеmy mhujer/fio-api-php library и the build matrix on Travis CI
Хотя это устраняет большинство несовместимостей, имейте в виду, что существует слишком много комбинаций минимальных и максимальных версий зависимостей. Они все еще могут быть несовместимы.
Совет № 8: Сортируйте пакеты в require и require-dev по имени
пара по имениrequire и require-devПакетный заказ — очень хорошая практика. Это позволяет избежать ненужных конфликтов слияния при перемещении ветки. Если вы добавите пакет в конец списка в двух файлах ветвей, вы можете столкнуться с конфликтами при каждом слиянии. Ручная сортировка пакетов была бы утомительной, поэтому лучший способ сделать это —composer.jsonсередина настроить егоТы сможешь:{
...
"config": {
"sort-packages": true
},
...
}
позжеrequireНовый пакет, который автоматически добавляется в нужное место (не бегая в хвост).
Совет № 9. Не выполняйте слияние при перебазировании или слиянии версийcomposer.lock
если тыcomposer.json (и composer.lock) и еще одна зависимость в главной ветке до того, как ветка была объединена, вам необходимо перебазировать вашу ветку. Такcomposer.lockФайл получит конфликт слияния. Никогда не пытайтесь разрешать конфликты вручную, потому чтоcomposer.lockфайл содержит определенияcomposer.jsonХэш зависимостей в . Таким образом, даже если вы разрешите конфликт, окончательный объединенный файл блокировки все равно будет неправильным. Лучшее решение - сделать это, создать.gitattributesфайл, он скажет git не пытатьсяcomposer.lockОперация слияния файлов:/composer.lock -merge
рекомендоватьTrunk Based DevelopmentСпособ (обычно хороший, не может пойти не так) использовать временную ветку функций, чтобы исправить эту проблему. Если у вас есть временная ветка, которую нужно объединить на лету, результирующийcomposer.lockРиск конфликтов слияния файлов минимален. Вы даже можете разветвиться, просто чтобы добавить зависимость, а затем сразу же объединиться.
Если в процессе дериватизацииcomposer.lockЧто делать, если возникает конфликт слияния? Используйте версию основной ветки для решения, поэтому изменяйте толькоcomposer.jsonфайл (добавить новый пакет). затем бегиcomposer update --lock, поставлюcomposer.jsonМодификация файла обновлена доcomposer.lockв файле. Теперь обновитеcomposer.lockФайл фиксируется в промежуточной области версии, и операция перебазирования продолжается.
Совет № 10: Знайтеrequire и require-devразница между
быть осведомленнымrequire иrequire-devРазличие между модулями очень важно. Пакеты, которые необходимо запустить в приложении или библиотеке, должны быть определены вrequire(например: Symfony, Doctrine, Twig, Guzzle, ...). Если вы создаете библиотеку,
Обратите внимание, что определяется какrequire. Потому что каждая зависимость в этом разделе также является зависимостью приложения, использующего библиотеку.Пакеты, необходимые для разработки приложения (или библиотеки), должны быть определены в
require-dev(например: PHPUnit, PHP_CodeSniffer, PHPStan).
Совет № 11: Безопасно обновляйте зависимости
Я думаю, что существует консенсус в отношении того, что зависимости должны регулярно обновляться. Что я хочу обсудить здесь, так это то, что обновление зависимостей должно быть четким и осторожным, а не только из-за необходимости других задач. Если вы обновляете библиотеку одновременно с рефакторингом приложения, может быть трудно определить, вызвана ли причина сбоя приложения рефакторингом или обновлением.
доступныйcomposer outdatedКоманда, чтобы увидеть, какие зависимости необходимо обновить. добавить--direct (или -D) переключение параметров — умный ход, это касается толькоcomposer.jsonуказанные зависимости. есть еще один-mПереключатель параметров, просмотрите только список обновлений младших номеров версий.Чтобы обновить каждую старую версию зависимости, выполните следующие действия:
- Создать новую ветку
- существует
composer.jsonОбновите версию зависимости до последнего номера версии в файле. - бегать
composer update phpunit/phpunit --with-dependencies(заменить обновленной библиотекойphpunit/phpunit) - Проверьте файл CHANGELOG в репозитории репозитория на Github на наличие критических изменений. Обновите приложение, если оно существует
- Протестируйте приложение локально (вы также можете увидеть предупреждения об устаревании на панели отладки при использовании Symfony)
- Внести поправки (в т.ч.
composer.json,composer.lockи другие изменения, необходимые для правильной работы новой версии) - Дождитесь завершения сборки CI
- объединить, а затем развернуть
Иногда необходимо обновить сразу несколько зависимостей, например, при обновлении Doctrine или Symfony. В этом случае перечислите их все в команде обновления:
composer update symfony/symfony symfony/monolog-bundle --with-dependencies
Или используйте подстановочные знаки для обновления всех зависимостей указанного пространства имен:
composer update symfony/* --with-dependencies
Это утомительная работа, но она обеспечивает дополнительную защиту от случайного обновления зависимостей.
Приемлемый ярлык - обновить все сразуrequire-devЗависимости в (если код программы не изменялся, в противном случае рекомендуется создать отдельную ветку для проверки кода).
Совет № 12: Вcomposer.jsonОпределите другие типы зависимостей в
Помимо определения библиотек в качестве зависимостей, здесь можно определить и другие вещи.
Версии PHP, поддерживаемые приложениями и библиотеками, можно определить:
"require": {
"php": "7.1.* || 7.2.*",
},
Также могут быть определены расширения, необходимые приложениям и библиотекам. Это очень полезно при попытке докеризации собственного приложения или когда ваши коллеги впервые настраивают среду приложения.
"require": {
"ext-mbstring": "*",
"ext-pdo_mysql": "*",
},
*).
Совет № 13: Проверяйте во время сборки CIcomposer.json
composer.json и composer.lockдолжны постоянно синхронизироваться. Поэтому рекомендуется постоянно выполнять их автоматическую проверку. Добавление этого как части сценария сборки обеспечитcomposer.lock и composer.jsonСинхронизируйтесь:composer validate --no-check-all --strict
Совет № 14: Используйте плагин Composer в PHPStorm
вотcomposer.json plugin for PHPStorm, При ручном измененииcomposer.json, плагин автоматически завершит и выполнит некоторую проверку.Если вы используете другую IDE (или просто редактор), вы можете использоватьits JSON schemaНастройте аутентификацию.
Совет № 15: Вcomposer.jsonУказывает номер версии PHP рабочей среды.
Если вы похожи на меня, иногдаЛокальный запуск последней предварительной версии PHP, то вы рискуете обновить версию зависимости, чтобы она не работала в рабочей среде. Сейчас я использую PHP 7.2.0, а это значит, что установленные мной библиотеки могут не работать в 7.1. Если производственная среда работает
7.1 установка невозможна. Но не волнуйтесь, есть очень простое решение, вcomposer.jsonдокументconfigЧастично укажите номер версии PHP рабочей среды:"config": {
"platform": {
"php": "7.1"
}
}
requireНекоторые настройки перепутаны и работает по-разному. После этого ваше приложение может работать под версией 7.1 или 7.2, а также указать версию платформы как 7.1 (это означает, что обновленная версия зависимостей должна быть совместима с версией платформы 7.1):"require": {
"php": "7.1.* || 7.2.*"
},
"config": {
"platform": {
"php": "7.1"
}
},
Совет № 16: Используйте приватные пакеты на собственном Gitlab
Рекомендуемое использованиеvcsв качестве типа репозитория, а Composer выбирает подходящий способ получения пакета. Например, добавьте ответвление от Github и используйте его API для загрузки ZIP-файла всего репозитория без клонирования. Но это сложнее для частной установки Gitlab. Если вы используетеvcsВ качестве типа репозитория Composer обнаружит, что это установка типа Gitlab, и попытается использовать
Пакет загрузки API (для этого требуется ключ API. Я не хотел его устанавливать, поэтому просто клонировал и установил с помощью SSH): Сначала укажите, что тип репозитория —git:"repositories": [
{
"type": "git",
"url": "git@gitlab.mycompany.cz:package-namespace/package-name.git"
}
]
Затем укажите часто используемые пакеты:
"require": {
"package-namespace/package-name": "1.0.0"
}
Совет № 17: Временно используйте ветки исправления ошибок форка
Если вы нашли ошибку в публичной библиотеке и исправили ее в своем собственном форке на Github, вам необходимо установить библиотеку из собственного репозитория, а не официальной (которая будет объединена и исправлена до выхода исправления) версии).
использовать встроенный псевдонимЭто легко сделать:{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/you/monolog"
}
],
"require": {
"symfony/monolog-bundle": "2.0",
"monolog/monolog": "dev-bugfix as 1.0.x-dev"
}
}
pathкак тип репозиторияПротестируйте это исправление локально перед отправкой обновленного репозитория.
Обновлено 08.01.2018:
После того, как статья была опубликована, я получил несколько советов о том, как ее использовать. они соответственно:
Совет № 18: ускорьте установку пакета с prestissimo
У композитора естьhirak/prestissimoПлагины, с помощью которых загрузки могут выполняться параллельно, тем самым повышая скорость установки зависимых пакетов.Итак, такая хорошая вещь, что вы делаете сейчас? Вам просто нужно установить этот плагин глобально прямо сейчас, и тогда он будет доступен во всех проектах автоматически.
composer global require hirak/prestissimoСовет № 19. Если вы не уверены, проверьте ограничения версии
даже во время чтенияthe documentationПосле этого написание правильных ограничений версии может иногда вызывать затруднения.Packagist Semver CheckerМожет использоваться для проверки того, какая локаль соответствует определенному ограничению. Он не просто анализирует ограничения версии, он начинает сPackagistЗагрузите данные, чтобы показать актуальную версию выпуска.the result for symfony/symfony:^3.1.
Совет № 20: Используйте авторитетные файлы classmap в рабочей среде
Должно быть в производственной средеСоздать авторитетный файл карты классов. Это позволяет быстро загружать все классы, содержащиеся в файле classmap, без необходимости обращения к файловой системе диска для каких-либо проверок.Вы можете запустить следующие команды во время производственной сборки:
composer dump-autoload --classmap-authoritative
Совет № 21: Настройте для тестированияautoload-dev
Вы также не хотите загружать тестовые файлы в рабочей среде (учитывая размер тестового файла и использование памяти). Это можно настроить с помощьюautoload-devрешить (сautoloadсходство):"autoload": {
"psr-4": {
"Acme\\": "src/"
}
},
"autoload-dev": {
"psr-4": {
"Acme\\": "tests/"
}
},Совет № 22: Попробуйте скрипты Composer
ComposerScript — это легкий инструмент для создания скриптов сборки. По этому поводу у меняупоминается в другом.Суммировать
Если вы с чем-то не согласны и укажите, почему вы не согласны (не забудьте отметитьtipid) Я буду счастлив.
Все переводы в этой статье предназначены только для обучения и общения, при перепечатке обязательно указывайте переводчика, источник и ссылку на эту статью.
Наша работа по переводу следуетСС соглашение, если наша работа нарушает ваши права, пожалуйста, свяжитесь с нами вовремя.