Spec-Zone.ru › Composer

Обработка частных пакетов

Частный Packagist

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

Частный Packagist доступен как хостинг SaaS-решение или как самохостинговый пакет на локальном сервере, предоставляя интерактивный процесс настройки.

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

Satis

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

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

Настройка

Например, предположим, что у вас есть несколько пакетов, которые вы хотите повторно использовать в вашей компании, но не хотите открывать исходный код. Сначала вы определите конфигурацию 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, вы можете использовать встроенный сервер командной строки php -S localhost:port -t satis-output-dir/ для временного решения.

Частичные обновления

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

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

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

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

Если вы хотите просканировать только выбранный пакет, а не все репозитории VCS, вам нужно объявить имя для всех ваших пакетов (это работает только с репозиториями типа 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, используя 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"
    }
}

Безопасность

Для защиты вашего частного репозитория вы можете разместить его через 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 на вашем локальном satis, процесс сборки будет включать расположение загрузок, предоставляемых этими платформами. Это означает, что репозиторий и ваша настройка зависят от доступности этих сервисов.

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

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

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

Объяснение опций

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

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

Префикс 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 на автоматическое разрешение и добавление всех зависимостей для ваших проектов. Это можно использовать с функцией Загрузки для создания полного локального зеркала пакетов. Добавьте следующее в ваш satis.json:

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

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

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

Другие опции

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

© Nils Adermann, Jordi Boggiano
Licensed under the MIT License.
https://getcomposer.org/doc/articles/handling-private-packages.md

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API