PHP: как применять собственные исправления к пакетам Composer

Использование сторонних пакетов может ускорить разработку вашего проекта. Иногда вам может понадобиться добавить дополнительные функции или исправить критическую ошибку. Вот как применять исправления к пакетам PHP, установленным Composer.

Когда исправлять пакет

Сначала подумайте, уместно ли создавать патч в проекте. Патч всегда должен быть незначительным изменением. Если вам нужно добавить обширную новую функциональность, вы должны открыть проблему с пакетом или создать его самостоятельно. Это поможет избежать конфликтов по мере развития пакета.

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

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

Создание патча Composer

После того, как вы сделали запрос на исправление, вы можете начать подготовку своего проекта. В Composer нет встроенной поддержки исправлений, поэтому мы воспользуемся популярным проектом simplify/vendor-patches, чтобы добавить его. Это обеспечивает интуитивно понятный интерфейс поверх cweagans/composer-patches, помогающий создавать новые исправления.

composer require --dev symplify/vendor-patches

Убедитесь, что пакет, который нужно исправить, установлен в вашем проекте:

composer require example/broken-package

Затем откройте проблемный файл в редакторе кода. Вы найдете его в каталоге vendor. В нашем примере нам нужно отредактировать vendor/example/broken-package/src/Broken.php:

<?php
 
class Broken {
    public function __construct(string|int $foo) {
        if (is_string($foo)) {
            echo "Valid value!";
        }
    }
}
 
?>

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

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

Скопируйте поврежденный файл без изменений и добавьте суффикс .old:

cp vendor/example/broken-project/src/Broken.php vendor/example/broken-project/src/Broken.php.old

Убедитесь, что вы не редактируете файл .old!

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

<?php
 
class Broken {
    public function __construct(string|int $foo) {
        if (is_string($foo)) {
            echo "Valid value!";
        }
        else if (is_int($foo)) {
            echo "Also valid!";
        }
    }
}
 
?>

Создание файла исправления

Теперь вы можете использовать проект symplify/vendor-patches для создания файла исправления для исправления. Пакет содержит двоичный файл vendor-patches, который автоматически сканирует ваш каталог vendor, чтобы найти внесенные вами изменения.

vendor/bin/vendor-patches generate

Запуск команды создаст для вас diff. Он будет сохранен в каталоге patches в корне вашего проекта. Разница рассчитывается путем сравнения созданных вами файлов .php и .php.old.

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

Автоматическое исправление

В вашем файле composer.json вы увидите, что был добавлен новый раздел:

{
    "extra": {
        "patches": {
            "example/broken-package": [
                "patches/example-broken-package-src-broken-php.patch"
            ]
        }
    }
}

Объект patches сопоставляет имена установленных пакетов с массивом файлов исправлений, которые необходимо применить. Эти исправления будут применяться автоматически при каждой установке Composer.

Сценарий установки регистрируется с помощью simplify/vendor-patches. Он вызывается после установки каждой зависимости. Сценарий проверяет, были ли определены какие-либо исправления для пакета. Он автоматически применит все, что найдет.

Вы увидите строки в выводе composer install, указывающие, когда были применены исправления. Если сообщается об ошибке, вы можете использовать composer install --verbose, чтобы получить дополнительную информацию о том, почему исправление было пропущено. Это часто происходит из-за того, что обновление пакета устраняет исправленную вами проблему, что делает ваш файл исправления излишним.

Удаление патчей

Вы можете временно удалить патч, удалив его строку из composer.json. Это остановит применение исправления при установке композитора.

Чтобы навсегда удалить патч из проекта, удалите его строку composer.json. Затем вы можете удалить его файл .patch из каталога patches вашего проекта.

Если вы хотите отменить исправление, которое вы применили локально, проще всего выполнить описанные выше шаги, чтобы удалить или отключить исправление. Затем вы можете удалить пакет из каталога vendor и запустить composer install, чтобы вернуться к исходному состоянию.

---

---