Обработка приватных пакетов в Composer

• Private Packagist
• Satis
• Установка с помощью Composer из приватных хранилищ
  • Частичные обновления приватных пакетов в Composer
• Применение приватных пакетов в Composer
  • Безопасность применения приватных пакетов в Composer
  • Аутентификация
  • Загрузки
    • Варианты применения
    • prefix-url
  • Выходы в Сеть
  • Брошенные пакеты
  • Решение проблем зависимостей
  • Другие варианты

Private Packagist

Private Packagist - это коммерческий продукт для хостинга пакетов, предлагающий профессиональную поддержку и web-управление частными и публичными пакетами, а также возможность разграничения прав доступа. Private Packagist обеспечивает зеркалирование zip-файлов пакетов, что делает установку более быстрой и независимой от сторонних систем - например, благодаря зеркалированию zip-файлов возможно развертывание, даже если GitHub не работает.

Private Packagist доступен как SaaS-решение на хостинге или как самостоятельный пакет на локальном хостинге, обеспечивающий интерактивную настройку.

Часть доходов Private Packagist используется для оплаты разработки и хостинга Composer и Packagist.org, поэтому его использование - хороший способ финансово помочь в поддержке этих проектов с открытым исходным кодом. Более подробную информацию о том, как создать свой собственный архив пакетов, можно найти на Packagist.com.

Satis

Satis, с другой стороны, является открытым исходным кодом, но только генератором статического репозитория composer. Он похож на сверхлегкую, основанную на статических файлах версию packagist и может использоваться для размещения метаданных закрытых пакетов вашей компании или ваших собственных. Вы можете получить его с GitHub или установить через CLI:

php composer.phar create-project composer/satis --stability=dev --keep-vcs

Установка с помощью Composer из приватных хранилищ

Допустим, у вас есть несколько пакетов, которые планируется повторно использовать в компании, но вы не хотите открывать исходный код. Сначала вы определите конфигурацию Satis: json-файл, в котором перечислены ваши закрытые репозитории.

По умолчанию файл называется satis.json, но это может быть любое имя.

Ниже приведен пример конфигурации, вы видите, что она содержит несколько VCS-репозиториев, но это могут быть любые типы репозиториев. Затем он использует "require-all": true, который выбирает все версии всех пакетов в определенных вами репозиториях.

По умолчанию Satis ищет файл satis.json в корне репозитория.

{
    "name": "my/repository",
    "homepage": "http://packages.example.org",
    "repositories": [
        { "type": "vcs", "url": "https://github.com/mycompany/privaterepo" },
        { "type": "vcs", "url": "http://svn.example.org/private/repo" },
        { "type": "vcs", "url": "https://github.com/mycompany/privaterepo2" }
    ],
    "require-all": true
}

Если требуется выборочно установить нужные пакеты, вы можете перечислить все пакеты, которые нужно иметь в вашем репозитории satis, в классическом ключе composer require, используя ограничение "*", чтобы убедиться, что выбраны все версии, или другое ограничение, если требуются действительно конкретные версии.

{
    "repositories": [
        { "type": "vcs", "url": "https://github.com/mycompany/privaterepo" },
        { "type": "vcs", "url": "http://svn.example.org/private/repo" },
        { "type": "vcs", "url": "https://github.com/mycompany/privaterepo2" }
    ],
    "require": {
        "company/package": "*",
        "company/package2": "*",
        "company/package3": "2.0.0"
    }
}

Как только вы это сделаете, запускайте:

php bin/satis build <configuration file> <build dir>

После того как вы отладите этот процесс, как правило, эта команда запускается как задание cron на сервере. Она обновит всю информацию о ваших пакетах, подобно тому, как это делает Packagist.

Обратите внимание, что если ваши частные пакеты размещены на GitHub, ваш сервер должен иметь ssh-ключ, который дает ему доступ к этим пакетам, и тогда вы должны добавить флаг --no-interaction (или -n) к команде, чтобы убедиться, что она переходит к аутентификации по ssh-ключу, а не запрашивает пароль. Это также хороший трюк для серверов непрерывной интеграции.

Настройте виртуальный хост, указывающий на каталог web/, допустим, packages.example.org. В качестве альтернативы, если PHP >= 5.4.0, вы можете использовать встроенный CLI-сервер php -S localhost:port -t satis-output-dir/ для временного решения.

Частичные обновления приватных пакетов в Composer

Вы можете указать Satis выборочно обновлять только определенные пакеты или обрабатывать только хранилище с заданным URL. Это сокращает время пересборки файла package.json и полезно, если используются (пользовательские) специальные webhooks для запуска пересборки всякий раз, когда код попадает в один из ваших репозиториев.

Чтобы пересобрать только определенные пакеты, передайте имена пакетов в командной строке следующим образом:

php bin/satis build satis.json web/ this/package that/other-package

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

Если вы хотите сканировать только выбранный пакет, а не все VCS-репозитории, необходимо объявить name для всех пакетов (это работает только для VCS-репозиториев):

{
    "repositories": [
        { "name": "company/privaterepo", "type": "vcs", "url": "https://github.com/mycompany/privaterepo" },
        { "name": "private/repo", "type": "vcs", "url": "http://svn.example.org/private/repo" },
        { "name": "mycompany/privaterepo2", "type": "vcs", "url": "https://github.com/mycompany/privaterepo2" }
    ]
}

Если вы хотите просканировать только один репозиторий и обновить все пакеты, найденные в нем, передайте URL репозитория VCS в качестве дополнительного аргумента:

php bin/satis build --repository-url https://only.my/repo.git satis.json web/

Применение приватных пакетов в Composer

В ваших проектах теперь достаточно добавить собственный репозиторий Composer, используя packages.example.org в качестве URL, затем запросить свои личные пакеты, и все будет работать гладко. Вам больше не нужно копировать все свои репозитории в каждый проект. Только один уникальный репозиторий, который будет обновляться сам.

{
    "repositories": [ { "type": "composer", "url": "http://packages.example.org/" } ],
    "require": {
        "company/package": "1.2.0",
        "company/package2": "1.5.2",
        "company/package3": "dev-master"
    }
}

Безопасность применения приватных пакетов в Composer

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

Пример использования пользовательского репозитория с помощью SSH (требуется расширение SSH2 PECL):

{
    "repositories": [{
        "type": "composer",
        "url": "ssh2.sftp://example.org",
        "options": {
            "ssh2": {
                "username": "composer",
                "pubkey_file": "/home/composer/.ssh/id_rsa.pub",
                "privkey_file": "/home/composer/.ssh/id_rsa"
            }
        }
    }]
}

Совет: Дополнительные сведения см. в разделе Параметры режима ssh2.

Пример использования SSL/TLS (HTTPS) с использованием сертификата клиента:

{
    "repositories": [{
         "type": "composer",
         "url": "https://example.org",
         "options": {
             "ssl": {
                 "local_cert": "/home/composer/.ssl/composer.pem"
             }
         }
    }]
}

Совет: Дополнительные сведения см. в разделе Параметры интерфейса ssl.

Пример использования пользовательского поля заголовка HTTP для аутентификации с помощью токена:

{
    "repositories": [{
        "type": "composer",
        "url": "https://example.org",
        "options":  {
            "http": {
                "header": [
                    "API-TOKEN: YOUR-API-TOKEN"
                ]
            }
        }
    }]
}

Аутентификация

Аутентификация может осуществляться несколькими различными способами.

Загрузки

Когда репозитории GitHub, GitLab или BitBucket зеркалируются на вашем локальном компьютере, процесс сборки будет включать местоположение загрузок, которые эти платформы делают доступными. Это означает, что репозиторий и ваша настройка зависят от доступности этих сервисов.

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

Чтобы позволить вашей установке satis создавать загрузки для всех (Git, Mercurial и Subversion) ваших пакетов, добавьте следующее в ваш satis.json:

{
    "archive": {
        "directory": "dist",
        "format": "tar",
        "prefix-url": "https://amazing.cdn.example.org",
        "skip-dev": true
    }
}

Варианты применения

• directory: обязательный, расположение дистрибутивных файлов (внутри output-dir).
• format: необязательный, zip (по умолчанию) или tar.
• prefix-url: необязательный, местоположение загрузок, по умолчанию домашняя страница (из satis.json), за которой следует directory.
• skip-dev: необязательный, по умолчанию false, при включении true satis не будет создавать загрузки для branches.
• absolute-directory: необязательный, локальный каталог, в который будут сбрасываться файлы дистрибутивов вместо output-dir/directory.
• whitelist: необязательный, если задан как список имен пакетов, satis будет сбрасывать файлы дистрибутивов только этих пакетов.
• blacklist: необязательный, если задан как список имен пакетов, satis не будет делать дамп файлов дистрибутивов этих пакетов.
• checksum: необязательный, по умолчанию true, при отключении false satis не будет предоставлять контрольную сумму sha1 для файлов дистрибутивов.

После включения этой опции все загрузки (включая загрузки с GitHub и BitBucket) будут заменены локальной версией.

prefix-url

Префикс URL с другим хостом особенно полезен, если загрузка заканчивается в частном хранилище Amazon S3 или на хосте CDN. CDN значительно улучшит время загрузки и, следовательно, установку пакета.

Пример: prefix-url https://my-bucket.s3.amazonaws.com (и directory установлен на dist) создает URL загрузки, который выглядит следующим образом: https://my-bucket.s3.amazonaws.com/dist/vendor-package-version-ref.zip.

Выходы в Сеть

• output-html: необязательный, по умолчанию true, при отключении false satis не будет генерировать страницу output-dir/index.html.
• twig-template: необязательный, путь к персонализированному шаблону Twig для страницы output-dir/index.html.

Брошенные пакеты

Чтобы ваша установка satis указывала на то, что некоторые пакеты заброшены, добавьте следующее в ваш satis.json:

{
    "abandoned": {
        "company/package": true,
        "company/package2": "company/newpackage"
    }
}

Значение true означает, что пакет действительно заброшен, а значение "company/newpackage" указывает на то, что пакет заменяется пакетом company/newpackage.

Обратите внимание, что все пакеты, установленные как заброшенные в их собственном файле composer.json, также будут помечены как заброшенные.

Решение проблем зависимостей

Можно сделать так, чтобы satis автоматически разрешал и добавлял все зависимости для ваших проектов. Его можно использовать вместе с функциональностью Downloads, чтобы иметь полное локальное зеркало пакетов. Добавьте следующее в ваш satis.json:

{
    "require-dependencies": true,
    "require-dev-dependencies": true
}

При поиске пакетов satis будет пытаться получить все необходимые пакеты из перечисленных репозиториев. Поэтому, если вы требуете пакет из Packagist, вам нужно будет определить его в вашем satis.json.

Зависимости Dev собираются только в том случае, если параметр require-dev-dependencies имеет значение true.

Другие варианты

• providers: необязательный, по умолчанию false, при включении true каждый пакет будет сбрасываться в отдельный включаемый файл, который будет загружаться Composer'ом только тогда, когда пакет действительно необходим. Ускоряет работу с composer для репозиториев с огромным количеством пакетов, таких как, например, packagist.
• output-dir: необязательный, определяет, куда выводить файлы репозитория, если они не указаны в качестве аргумента при вызове команды build.
• config: необязательный, позволяет определить все опции конфигурации из composer, кроме archive-format и archive-dir, так как конфигурация выполняется через archive. Более подробную информацию смотрите в документации по schema config.
• notify-batch: необязательный, указывает URL, который будет вызываться каждый раз, когда пользователь устанавливает пакет. См. раздел notify-batch.

Перевод с английского официальной документации Composer:
https://getcomposer.org/doc/articles/handling-private-packages.md

Заберите ссылку на статью к себе, чтобы потом легко её найти!
Раз уж досюда дочитали, то может может есть желание рассказать об этом месте своим друзьям, знакомым и просто мимо проходящим?
Не надо себя сдерживать! ;)