Composer — PHP: Настройка окружения

Ключевая программа в экосистеме PHP — Composer. Она выполняет очень много функций, которые не представляется возможным рассмотреть в рамках текущего курса. Общая рекомендация состоит в том, чтобы периодически посматривать на её команды и изучать информацию по ним. Ключевая задача, которую решает Composer — управление зависимостями, и именно о ней мы поговорим. Процесс установки самого Composer для каждой операционной системы описан в официальном руководстве:

• https://getcomposer.org/download/
• https://getcomposer.org/doc/00-intro.md#installation-linux-unix-macos

Для успешной установки и настройки Composer, необходимо хотя бы немного разбираться с работой командных интерпретаторов. Рекомендуем пройти соответствующий курс на Хекслете, если вы этого ещё не сделали

Кроме самого Composer установите следующие программы, используя пакетный менеджер вашей операционной системы:

• git
• curl

Убедитесь, что Composer работает:

composer
   ______
  / ____/___  ____ ___  ____  ____  ________  _____
 / /   / __ \/ __ `__ \/ __ \/ __ \/ ___/ _ \/ ___/
/ /___/ /_/ / / / / / / /_/ / /_/ (__  )  __/ /
\____/\____/_/ /_/ /_/ .___/\____/____/\___/_/
                    /_/
Composer version 1.8.0 2018-12-03 10:31:16

# Тут много вывода

Запуск Composer без аргументов, выведет весь список доступных команд с их описанием. Пробегитесь по ним, чтобы сформировать первое впечатление.

Практически с самого зарождения программирования (когда код стал храниться в памяти компьютера), появилась идея повторного использования кода не только в рамках одного проекта, но и в других проектах. Например, функции для работы с датами, математическими формулами, всевозможными расчётами одни и те же во всех проектах, где они требуются. Подобное переиспользование приводит к резкому возрастанию производительности. Программисты современности могут сосредоточиться на решении уникальных задач бизнеса, вместо создания своих велосипедов для решения инфраструктурных задач. Особенно просто стало жить во времена Git и GitHub.

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

1. Сложно передать другим
2. У каждого своя собственная копия одних и тех же решений (немного разных решений)
3. Доработкой занимается только автор
4. В сумме много разных копий без возможности быстрого обновления
5. Из-за того, что код копируется прямо в другой проект, он, как правило, модифицируется и становится специфичным

Если использовать Git, то часть проблем решается автоматически. Мы можем сказать, что набор общих файлов называется "библиотека", а конечные проекты начинают использовать библиотеки как написанные нами, так и сторонними разработчиками. Но тут возникает следующая сложность — когда таких библиотек становится много, то у них также появляется общий код более низкого уровня. Например, финансовые библиотеки могут использовать функции для преобразования валют. Чтобы подобный код не дублировался, хочется его вынести в общее место. Этот процесс может продолжаться бесконечно. Одни библиотеки зависят от других, те в свою очередь от третьих и так далее. С точки зрения переиспользования кода всё хорошо, большое число маленьких библиотек, решающих всевозможные задачи, позволяет быстро двигаться вперёд, но с точки зрения управления появляются проблемы:

1. Необходимо ввести понятие "версия", а библиотеки начинают зависеть не только друг от друга, но и от версий друг друга. Почему это нужно? Очень просто. Предположим, что создатель библиотеки обновил её, изменив сигнатуры функций (другое число параметров, другие параметры, другой возврат), или, как говорят, сломал обратную совместимость. В такой ситуации наша первоначальная библиотека перестанет работать (если мы обновим вторую библиотеку), так как она рассчитывала на одно поведение зависимой библиотеки, а получила другое.
2. Необходимо стандартизировать способ создания библиотек, только в таком случае станет возможным автоматизировать процесс их соединения без ручного управления. Скажу навскидку, типичный веб-проект может зависеть от сотни библиотек, которые в свою очередь зависят от других библиотек. Общее число зависимостей может легко перевалить за тысячу. Вручную управлять таким зоопарком не представляется возможным.
3. Проблема, описанная выше, также требует наличия автоматизированного средства по управлению зависимостями. Обновлению, установке и удалению.

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

Терминология

В PHP используются следующие понятия.

Пакет — собственно, та самая библиотека, которую мы либо пишем, либо используем в проекте как зависимость.

Репозиторий (Registry) — хранилище пакетов PHP, которое называется Packagist. Каждый желающий может опубликовать пакет в Packagist, потратив буквально минуту времени, а остальные смогут его использовать. В хранилище, на текущий момент, сотни тысяч пакетов и их количество растёт. Исходный код пакетов, как правило, хранится на GitHub, но это не обязательно.

Глобальная установка пакетов

Многие пакеты в PHP представляют из себя законченные программы. Их можно установить и запустить как обычную утилиту командной строки. Эти пакеты ставятся в системные директории и не связаны с конкретным проектом.

Попробуем установить утилиту phpcs, которая анализирует код на соответствие стандартам. Инструкция по установке подобных пакетов обычно присутствует на странице репозитория на GitHub.

# Composer скачает исходный код этого пакета и положит его куда-то к себе.
# Конкретный путь зависит от настроек и операционной системы
composer global require 'squizlabs/php_codesniffer=*'

• global означает, что установка глобальная, то есть пакет ставится в операционную систему как обычная программа.
• Чтобы командный интерпретатор увидел программу, установленную глобально, нужно правильно настроить переменную окружения $PATH добавив в неё путь к исполняемым файлам Composer. Его можно узнать выполнив в терминале команду composer global config bin-dir.

Процесс установки занимает некоторое время, в течение которого видно как скачивается не только сам пакет, но и его зависимости. Дальше ничего делать не нужно, так как phpcs создан утилитой командной строки, он сразу готов к использованию.

# Как аргумент эта утилита принимает путь до файла или директории с исходным кодом
# Здесь в качестве опции мы указываем также и стандарт PSR12
phpcs --standard=PSR12 path/to/file

FILE: /home/hexlet/projects/test/test.php
-------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
-------------------------------------------------------------------------------
 12 | ERROR | [x] Each imported trait must have its own "use" import statement
-------------------------------------------------------------------------------
PHPCBF CAN FIX THE 1 MARKED SNIFF VIOLATIONS AUTOMATICALLY
-------------------------------------------------------------------------------

Time: 21ms; Memory: 6MB

Если что-то пошло не так, убедитесь что вы всё правильно настроили:

• Изучите вывод echo $PATH. Есть ли там путь до исполняемых файлов Composer.

  echo $PATH

  /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/hex/.composer/vendor/bin

• Проверьте, все ли установилось командой which phpcs.

  which phpcs

  /home/hex/.composer/vendor/bin/phpcs

Ошибки

Во время установки пакетов, Composer может начать ругаться на различные ошибки. Например так:

- Installation request for phar-io/manifest 1.0.x-dev -> satisfiable by phar-io/manifest[1.0.x-dev].
- phar-io/manifest 1.0.x-dev requires ext-dom * -> the requested PHP extension dom is missing from your system.
Problem 2
- Installation request for phar-io/manifest dev-master -> satisfiable by phar-io/manifest[dev-master].
- phar-io/manifest dev-master requires ext-dom * -> the requested PHP extension dom is missing from your system.
Problem 3
- Installation request for phpunit/php-code-coverage 7.0.x-dev -> satisfiable by phpunit/php-code-coverage[7.0.x-dev].
- phpunit/php-code-coverage 7.0.x-dev requires ext-dom * -> the requested PHP extension dom is missing from your system.
  Problem 4

Эти ошибки говорят нам о том, что устанавливаемые библиотеки хотят использовать PHP-расширение, которое не установлено в систему. Это прямо написано в выводе:

requires ext-dom * -> the requested PHP extension dom is missing from your system.

Когда вы встречаете такую ошибку, то первым делом нужно увидеть название расширения. В данном случае это dom. Затем нужно попробовать найти инструкцию, которая объяснит как установить это расширение в вашу операционную систему. Проще всего это сделать таким запросом: php <название операционной системы> <название расширения> install extension.

Проект

Composer – универсальный способ описывать любой код на PHP. Не важно с чем мы имеем дело, с библиотекой или с полноценным сайтом. В любом случае внутри будет Composer. Фактически, любой новый проект начинается не с написания кода, а с инициализации Composer. Для этого нужно запустить команду init. Она задаст несколько вопросов и на основе ваших ответов сформирует файл composer.json.

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

composer init

Welcome to the Composer config generator

This command will guide you through creating your composer.json config.
Package name (<vendor>/<name>) [hex/hex]: hex/example
Description []: example package
Author [, n to skip]: hex <hex@hexlet.io>
Minimum Stability []:
Package Type (e.g. library, project, metapackage, composer-plugin) []:
License []:

Define your dependencies.

Would you like to define your dependencies (require) interactively [yes]? n
Would you like to define your dev dependencies (require-dev) interactively [yes]? n

{
    "name": "hex/example",
    "description": "example package",
    "authors": [
        {
            "name": "hex",
            "email": "hex@hexlet.io"
        }
    ],
    "require": {}
}
Do you  confirm generation [yes]?

Когда вопросы закончатся, Composer покажет конечный результат в виде JSON. JSON — это текстовый формат для представления структурированных данных. Если вы не знакомы с ним, то не стоит переживать, формат это не язык программирования. Достаточно выучить несколько правил по формированию данных в виде JSON для того, чтобы чувствовать себя комфортно.

{
    "name": "hex/example",
    "description": "example package",
    "authors": [
        {
            "name": "hex",
            "email": "hex@hexlet.io"
        }
    ],
    "require": {}
}

Если вас всё устраивает, то Composer создаст файл composer.json. Именно этот файл является ключевым. Абсолютно всё, что касается зависимостей (и не только), полностью описывается в нём. С этого момента, все команды composer, которые непосредственно связаны с проектом (о них пойдёт речь далее), выполняются именно в той директории, в которой находится файл composer.json.

Имя пакета, записанное в composer.json, состоит из двух частей. Первая — vendor name, имя, под которым вы зарегистрированы в Packagist, вторая — project name. Причём vendor name уникален глобально (то есть все пользователи имеют своё собственное неповторимое имя), а вот project name должен быть уникален только в пределах vendor name.

Composer рекомендует именовать пакет словами в нижнем регистре и в качестве разделителя использовать дефис, например: dependency-injection.

Проблемы

Если в файле composer.json содержатся синтаксические ошибки, иными словами, есть нарушения правила форматирования JSON, то при попытке сделать что-то с проектом будут появляться подобные ошибки:

[Seld\JsonLint\ParsingException]
"./composer.json" does not contain valid JSON
Parse error on line 2:
"name": "mokevnin/myproject",
---------^

Обычно любые сообщения с "неожиданными" (unexpected) символами или строками говорят о наличии синтаксической ошибки.

Воспользуйтесь валидаторами JSON для проверки корректности своего файла. Например, jsonlint.com или другими подобными инструментами, которые можно загуглить по запросу "json validator".

Самостоятельная работа

1. В проекте hexlet-php инициализируйте PHP-проект.
2. Заполните пустые поля файла composer.json, подробное описание каждого поля можно посмотреть в документации composer
3. Добавьте все изменения на гитхаб

Дополнительные материалы

1. Переменная PATH
2. Изменение переменной PATH

Остались вопросы? Задайте их в разделе «Обсуждение»

Вам ответят команда поддержки Хекслета или другие студенты.