Управление зависимостями — PHP: Настройка окружения

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

• Библиотеки для выполнения HTTP-запросов
• Библиотеки для парсинга различных форматов — например, XML, JSON, YAML.
• Библиотеки обработки URL, которые позволяют извлекать из них части и собирать обратно
• Фейкеры — библиотеки для генерации адресов, имен и других случайных данных
• Тестовые фреймворки. С их помощью код тестируется в автоматическом режиме (они используются во всех практиках на Хекслете)

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

Предположим, что наш пакет зависит от библиотеки illuminate/collections. Эту библиотеку мы будем активно использовать в наших курсах позже.

Разберем процесс установки. Для начала нужно понять, под каким именем существует наша библиотека в Packagist. Здесь может быть два варианта:

• Либо мы уже знаем имя, как в случае illuminate/collections
• Либо мы нашли библиотеку на GitHub и хотим выяснить ее имя

Часто имя можно извлечь из строки установки, которая есть в файле README.md:

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

{
    "name": "illuminate/collections",
    "description": "The Illuminate Collections package.",
    "license": "MIT",
    "homepage": "https://laravel.com",
    "support": {
        "issues": "https://github.com/laravel/framework/issues",
        "source": "https://github.com/laravel/framework"
    }
}

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

# Это локальная установка в конкретный проект
composer require illuminate/collections

Эта команда не только устанавливает зависимость в текущий проект, но и автоматически добавляет его в секцию require файла composer.json. Такая установка является локальной — в команде нет слова global. Другими словами, пакет ставится именно в текущий проект. Секция require теперь выглядит примерно так:

"require": {
    "illuminate/collections": "^11.0"
}

Кроме того, Composer создаст файл composer.lock в корне проекта. Этот файл должен храниться в репозитории, а его значение мы изучим в следующем уроке.

Со временем все больше пакетов добавляется в текущий проект, и размер секции require становится все больше. В крупных проектах это могут быть сотни зависимостей. Посмотрим на пример, взятый из php-package:

"require": {
    "illuminate/collections": "^11.0",
    "nesbot/carbon": "^3.0",
    "symfony/string": "^7.0",
}

У вас может возникнуть вопрос: «А куда помещается код этих пакетов?». Код пакетов, установленных локально, сохраняется в директории vendor, которую Composer автоматически создает во время установки пакетов. Эта директория находится в корне проекта:

tree -L 1

.
├── Makefile
├── README.md
├── bin
├── composer.json
├── composer.lock
├── phpunit.xml
├── psysh.php
├── src
├── tests
└── vendor # Вот она

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

Обычные зависимости нужны для работы пакета. Кроме них, существуют еще и специальные зависимости, необходимые только во время разработки. Такое разделение понадобилось в целях оптимизации.

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

composer require --dev phpunit/phpunit

В файле composer.json они появляются внутри секции require-dev:

"require-dev": {
  "phpunit/phpunit": "*"
}

Теперь самое интересное — как использовать установленные зависимости? В первую очередь, нужно смотреть документацию конкретной библиотеки на GitHub. Обычно там есть примеры или ссылка на описание. Например, в следующих уроках мы будем пользоваться библиотекой illuminate/collections. Она содержит десятки полезных функций для работы со строками. Изучим пример вызова:

<?php

collect([null, null, 'foo bar'])->filter(); // ['foo bar']
collect([])->isEmpty(); // true

$collection = collect(['first', 'second']);
$upper = $collection->toUpper(); // ['FIRST', 'SECOND']

Установка с нуля

После того как в проект устанавливаются зависимости, измененные файлы заливаются на GitHub. К ним относится как composer.json с добавленными в него описаниями зависимостей, так и файлы с исходным кодом, где эти зависимости используются. А вот директория vendor остается на локальной машине.

Представьте, что с вами работает другой разработчик, который клонирует репозиторий и пытается запустить проект локально. Что произойдет? Запуск кода завершится с ошибкой. В проекте используются внешние библиотеки, но их физически нет. Директория vendor не создана.

Чтобы исправить это, сразу после клонирования нужно выполнить установку зависимостей. Для этого в Composer есть еще одна команда – install:

composer install

# Ниже примерный вывод
Loading composer repositories with package information
Installing dependencies (including require-dev) from lock file
Warning: The lock file is not up to date with the latest changes in composer.json. You may be getting outdated dependencies. Run update to update them.
Package operations: 1 install, 19 updates, 18 removals
  - Removing symfony/yaml (dev-master)
  - Removing symfony/stopwatch (dev-master)
  - Removing symfony/polyfill-php73 (dev-master)
  - Removing symfony/filesystem (dev-master)
  - Removing symfony/event-dispatcher (dev-master)
  - Removing symfony/console (dev-master)
  - Removing symfony/config (dev-master)
  - Removing satooshi/php-coveralls (v1.1.0)
  - Removing psy/psysh (dev-master)
  - Removing padraic/phar-updater (dev-master)
  - Removing padraic/humbug_get_contents (1.1.2)
symfony/translation-contracts suggests installing symfony/translation-implementation
Generating autoload files

Установка пакетов — это идемпотентная операция, ее можно запускать сколько угодно раз без риска что-либо поломать.

Теперь самое интересное, как собственно использовать установленные зависимости? Ответ, как обычно находится в документации репозитория на гитхабе того пакета, который вы хотите использовать.

Создайте в корне вашего проекта папку src, а внутри нее файл Runner.php. Добавьте следующий код:

<?php

namespace My\Project\Runner;

use Illuminate\Support\Collection;

function run()
{
    $collection = collect(['taylor', 'abigail', null])->map(function ($name) {
    return strtoupper($name);
    });

    return $collection;
}

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

Eсли вы склонировали репозиторий с гитхаба, папка vendor будет отсутствовать как и пакеты в ней. Первое, что нужно будет сделать, выполнить команду composer install. Установка пакетов - идемпотентная операция, ее можно запускать сколько угодно раз и все будет хорошо.

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

1. Зарегистрируйтесь на сайте packagist.org — аккаунт пригодится для участия в проектах

2. Установите зависимость:

   # Выполните в корне проекта
   composer require illuminate/collections
   

3. В корне вашего проекта создайте директорию src, а внутри нее — файл Runner.php. Добавьте следующий код:

   <?php
   
   namespace Hexlet\Php\Runner;
   
   function run()
   {
       $collection = collect(['taylor', 'abigail', 'ivan'])->map(function ($name) {
           return strtoupper($name);
       });
   
       return $collection;
   }