Репозитории

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

Основные понятия

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

Пакет

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

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

Помимо имени и версии, есть полезные метаданные. Информация, наиболее важная для установки, — это определение источника, описывающее, где получить содержимое пакета. Данные пакета указывают на содержимое пакета. И здесь есть два варианта: dist и source.

Dist: Dist — это упакованная версия данных пакета. Обычно это выпущенная версия, обычно стабильная версия.

Source: Source используется для разработки. Обычно он берётся из репозитория исходного кода, такого как git. Вы можете получить его, когда захотите изменить загруженный пакет.

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

Репозиторий

Репозиторий — это источник пакетов. Это список пакетов/версий. Composer будет искать во всех ваших репозиториях, чтобы найти пакеты, необходимые вашему проекту.

По умолчанию в Composer зарегистрирован только репозиторий Packagist.org. Вы можете добавить больше репозиториев в свой проект, объявив их в composer.json.

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

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

Типы

Composer

Основной тип репозитория — composer репозиторий. Он использует один файл packages.json, содержащий все метаданные пакета.

Это также тип репозитория, который использует Packagist. Для ссылки на composer репозиторий, укажите путь перед файлом packages.json. В случае с Packagist, этот файл находится по адресу /packages.json, поэтому URL репозитория будет repo.packagist.org. Для example.org/packages.json URL репозитория будет example.org.

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://example.org"
        }
    ]
}

Пакеты

Единственное обязательное поле — packages. Структура JSON следующая:

{
    "packages": {
        "vendor/package-name": {
            "dev-master": { @composer.json },
            "1.0.x-dev": { @composer.json },
            "0.0.1": { @composer.json },
            "1.0.0": { @composer.json }
        }
    }
}

Маркер @composer.json будет содержать содержимое composer.json из этой версии пакета, включая как минимум:

name
version
dist или source

Вот минимальное определение пакета:

{
    "name": "smarty/smarty",
    "version": "3.1.7",
    "dist": {
        "url": "https://www.smarty.net/files/Smarty-3.1.7.zip",
        "type": "zip"
    }
}

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

Уведомление о партии

Поле notify-batch позволяет указать URL, который будет вызываться каждый раз, когда пользователь устанавливает пакет. URL может быть либо абсолютным путём (который будет использовать тот же домен, что и репозиторий), либо полным URL.

Пример значения:

{
    "notify-batch": "/downloads/"
}

Для example.org/packages.json содержащего пакет monolog/monolog, это отправит запрос POST на example.org/downloads/ с телом запроса в формате JSON:

{
    "downloads": [
        {"name": "monolog/monolog", "version": "1.2.1.0"}
    ]
}

Поле version будет содержать нормализованное представление номера версии.

Это необязательное поле.

metadata-url, available-packages и available-package-patterns

Поле metadata-url позволяет указать шаблон URL для предоставления всех пакетов в репозитории. Он должен содержать заполнитель %package%.

Это новое поле в Composer v2 и имеет приоритет над полями provider-includes и providers-url, если оба присутствуют. Для совместимости с Composer v1 и v2 желательно указать оба. Однако новые реализации репозиториев, возможно, потребуют поддержки только v2.

Пример:

{
    "metadata-url": "/p2/%package%.json"
}

Всякий раз, когда Composer ищет пакет, он заменяет %package% именем пакета и запрашивает этот URL. Если разрешена нестабильность разработки для пакета, он также загрузит URL снова с $packageName~dev (например, /p2/foo/bar~dev.json для поиска версий разработки foo/bar).

Файлы foo/bar.json и foo/bar~dev.json, содержащие версии пакетов, ДОЛЖНЫ содержать только версии пакета foo/bar, как {"packages":{"foo/bar":[ ... versions here ... ]}}.

Кэширование выполняется с помощью заголовка If-Modified-Since, поэтому убедитесь, что вы возвращаете заголовки Last-Modified и что они точны.

Массив версий также может быть опционально сжат с помощью Composer\MetadataMinifier\MetadataMinifier::minify() из composer/metadata-minifier. Если вы это сделаете, вы должны добавить ключ "minified": "composer/2.0" на верхнем уровне, чтобы указать Composer, что он должен восстановить список версий в исходные данные. См. https://repo.packagist.org/p2/monolog/monolog.json для примера.

Любой запрашиваемый пакет, которого нет, ДОЛЖЕН возвращать код состояния 404, что укажет Composer на то, что такого пакета нет в вашем репозитории. Убедитесь, что ответ 404 быстрый, чтобы избежать блокировки Composer. Избегайте перенаправлений на альтернативные страницы 404.

Если ваш репозиторий содержит небольшое количество пакетов, и вы хотите избежать запросов 404, вы также можете указать ключ "available-packages" в packages.json, который должен быть массивом со всеми именами пакетов, содержащихся в вашем репозитории. В качестве альтернативы вы можете указать ключ "available-package-patterns", который является массивом шаблонов имён пакетов (с * для соответствия любой строке, например, vendor/* заставит Composer искать каждый соответствующий пакет в этом репозитории).

Это необязательное поле.

API поставщиков

Поле providers-api позволяет указать шаблон URL для предоставления всех пакетов, которые предоставляют данное имя пакета, но не сам пакет с этим именем. Он должен содержать заполнитель %package%.

Например, https://packagist.org/providers/monolog/monolog.json перечисляет некоторые пакеты, которые имеют правило «provide» для monolog/monolog, но не сам monolog/monolog.

{
    "providers-api": "https://packagist.org/providers/%package%.json",
}

Это необязательное поле.

Список

Поле list позволяет возвращать имена пакетов, соответствующие заданному полю (или все имена, если фильтр отсутствует). Он должен принимать необязательный параметр запроса ?filter=xx, который может содержать * в качестве подстановочных символов, соответствующих любой подстроке.

Правила замещения/предоставления здесь не рассматриваются.

Он должен возвращать массив имён пакетов:

{
    "packageNames": [
        "a/b",
        "c/d"
    ]
}

См. https://packagist.org/packages/list.json?filter=composer/* для примера.

Это необязательное поле.

provider-includes и providers-url

Поле provider-includes позволяет перечислить набор файлов, которые перечисляют имена пакетов, предоставляемых этим репозиторием. Хэш должен быть sha256 файлов в этом случае.

Поле providers-url описывает, как файлы поставщиков находятся на сервере. Это абсолютный путь от корня репозитория. Он должен содержать заполнители %package% и %hash%.

Эти поля используются Composer v1 или если в вашем репозитории не задано поле metadata-url.

Пример:

{
    "provider-includes": {
        "providers-a.json": {
            "sha256": "f5b4bc0b354108ef08614e569c1ed01a2782e67641744864a74e788982886f4c"
        },
        "providers-b.json": {
            "sha256": "b38372163fac0573053536f5b8ef11b86f804ea8b016d239e706191203f6efac"
        }
    },
    "providers-url": "/p/%package%$%hash%.json"
}

Эти файлы содержат списки имён пакетов и хэши для проверки целостности файла, например:

{
    "providers": {
        "acme/foo": {
            "sha256": "38968de1305c2e17f4de33aea164515bc787c42c7e2d6e25948539a14268bb82"
        },
        "acme/bar": {
            "sha256": "4dd24c930bd6e1103251306d6336ac813b563a220d9ca14f4743c032fb047233"
        }
    }
}

Файл выше объявляет, что acme/foo и acme/bar можно найти в этом репозитории, загрузив файл, на который ссылается providers-url, заменив %package% именем пакета vendor и %hash% полем sha256. Эти файлы сами содержат определения пакетов, как описано выше.

Эти поля необязательны. Вам, вероятно, они не понадобятся для вашего собственного пользовательского репозитория.

Параметры cURL или потоков

Репозиторий доступен либо с помощью cURL (Composer 2 с включённым ext-curl), либо с помощью потоков PHP. Вы можете установить дополнительные параметры с помощью параметра options. Для потоков PHP вы можете установить любой допустимый параметр контекста потока PHP. См. Параметры и параметры контекста для получения дополнительной информации. При использовании cURL можно настроить только ограниченный набор параметров http и ssl.

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://example.org",
            "options": {
                "http": {
                    "timeout": 60
                }
            }
        }
    ],
    "require": {
        "acme/package": "^1.0"
    }
}

Система управления версиями (VCS)

VCS означает систему управления версиями. Это включает системы контроля версий, такие как git, svn, fossil или hg. Composer имеет тип репозитория для установки пакетов из этих систем.

Загрузка пакета из репозитория VCS

Существует несколько вариантов использования. Наиболее распространённым является поддержание собственной вилки сторонней библиотеки. Если вы используете определённую библиотеку для своего проекта, и вы решаете что-то изменить в библиотеке, вы захотите, чтобы ваш проект использовал исправленную версию. Если библиотека находится на GitHub (так бывает чаще всего), вы можете сделать её вилку там и отправить свои изменения на свою вилку. После этого обновите composer.json проекта. Всё, что вам нужно сделать, это добавить свою вилку как репозиторий и обновить ограничение версии, чтобы оно указывало на вашу пользовательскую ветку. Только в composer.json вы должны добавить префикс "dev-" к названию вашей пользовательской ветки (не делая его частью фактического имени ветки). Для соглашений об именах ограничений версий см. Библиотеки для получения дополнительной информации.

Пример, предполагающий, что вы исправили monolog, чтобы исправить ошибку в ветке bugfix:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/igorw/monolog"
        }
    ],
    "require": {
        "monolog/monolog": "dev-bugfix"
    }
}

При выполнении php composer.phar update вы должны получить свою изменённую версию monolog/monolog вместо той, что из Packagist.

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

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

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

Использование частных репозиториев

Точно такое же решение позволяет работать с вашими частными репозиториями в GitHub и Bitbucket:

{
    "require": {
        "vendor/my-private-repo": "dev-master"
    },
    "repositories": [
        {
            "type": "vcs",
            "url":  "git@bitbucket.org:vendor/my-private-repo.git"
        }
    ]
}

Единственное требование — установка SSH-ключей для клиента git.

Альтернативы Git

Git — не единственная поддерживаемая система управления версиями в репозитории VCS. Поддерживаются следующие системы:

Git: git-scm.com
Subversion: subversion.apache.org
Mercurial: mercurial-scm.org
Fossil: fossil-scm.org

Для получения пакетов из этих систем необходимо установить соответствующие клиенты. Это может быть неудобно. И по этой причине существует специальная поддержка GitHub и Bitbucket, которые используют API этих сайтов для получения пакетов без необходимости установки системы управления версиями. Репозиторий VCS предоставляет dist для них, которые загружают пакеты в виде zip-архивов.

GitHub: github.com (Git)
Bitbucket: bitbucket.org (Git)

Драйвер VCS для использования определяется автоматически на основе URL-адреса. Однако, если вам необходимо указать его по какой-либо причине, вы можете использовать bitbucket, github, gitlab, perforce, fossil, git, svn или hg в качестве типа репозитория вместо vcs.

Если вы установите ключ no-api на значение true в репозитории github, он будет клонирован как любой другой репозиторий git вместо использования API GitHub. Но в отличие от прямого использования драйвера git, Composer по-прежнему будет пытаться использовать zip-файлы github.

Обратите внимание:

Чтобы позволить Composer выбрать драйвер для использования, тип репозитория необходимо определить как «vcs»
Если вы уже использовали частный репозиторий, это означает, что Composer должен был клонировать его в кэш. Если вы хотите установить тот же пакет с драйверами, помните, что необходимо запустить команду composer clearcache и за ней команду composer update, чтобы обновить кэш Composer и установить пакет из dist.
Драйвер VCS git-bitbucket устарел в пользу bitbucket

Настройка драйвера Bitbucket

Обратите внимание, что конечная точка репозитория Bitbucket должна быть https, а не git.

После настройки вашего репозитория Bitbucket вам также необходимо настроить аутентификацию.

Параметры Subversion

Поскольку в Subversion нет встроенного понятия ветвей и тегов, Composer по умолчанию предполагает, что код расположен в $url/trunk, $url/branches и $url/tags. Если ваш репозиторий имеет другую структуру, вы можете изменить эти значения. Например, если вы использовали имена с заглавными буквами, вы можете настроить репозиторий следующим образом:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "http://svn.example.org/projectA/",
            "trunk-path": "Trunk",
            "branches-path": "Branches",
            "tags-path": "Tags"
        }
    ]
}

Если у вас нет каталогов ветвей или тегов, вы можете полностью отключить их, установив branches-path или tags-path в значение false.

Если пакет находится в подкаталоге, например, /trunk/foo/bar/composer.json и /tags/1.0/foo/bar/composer.json, то вы можете дать Composer доступ к нему, установив параметр "package-path" в подкаталог, в этом примере он будет "package-path": "foo/bar/".

Если у вас есть частный репозиторий Subversion, вы можете сохранить учетные данные в разделе http-basic своей конфигурации (см. Схема):

{
    "http-basic": {
        "svn.example.org": {
            "username": "username",
            "password": "password"
        }
    }
}

Если ваш клиент Subversion настроен на хранение учетных данных по умолчанию, эти учетные данные будут сохранены для текущего пользователя, и существующие сохраненные учетные данные для этого сервера будут перезаписаны. Чтобы изменить это поведение, установите параметр "svn-cache-credentials" в вашей конфигурации репозитория:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "http://svn.example.org/projectA/",
            "svn-cache-credentials": false
        }
    ]
}

Пакет

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

В сущности, вы определяете ту же информацию, что и в репозитории composer в packages.json, но только для одного пакета. Опять же, минимально необходимые поля — name, version и любой из dist или source.

Вот пример для шаблонизатора smarty:

{
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "smarty/smarty",
                "version": "3.1.7",
                "dist": {
                    "url": "https://www.smarty.net/files/Smarty-3.1.7.zip",
                    "type": "zip"
                },
                "source": {
                    "url": "http://smarty-php.googlecode.com/svn/",
                    "type": "svn",
                    "reference": "tags/Smarty_3_1_7/distribution/"
                },
                "autoload": {
                    "classmap": ["libs/"]
                }
            }
        }
    ],
    "require": {
        "smarty/smarty": "3.1.*"
    }
}

Обычно вы оставляете часть source, так как она вам не нужна.

Примечание: Этот тип репозитория имеет некоторые ограничения и следует избегать, когда это возможно:

Composer не будет обновлять пакет, пока вы не измените поле version.

Composer не будет обновлять ссылки на коммиты, поэтому если вы используете master в качестве ссылки, вам придется удалить пакет, чтобы принудительно обновить его, и придется иметь дело с нестабильным файлом блокировки.

Ключ "package" в репозитории package можно установить в массив, чтобы определить несколько версий пакета:

{
    "repositories": [
        {
            "type": "package",
            "package": [
                {
                    "name": "foo/bar",
                    "version": "1.0.0",
                    ...
                },
                {
                    "name": "foo/bar",
                    "version": "2.0.0",
                    ...
                }
            ]
        }
    ]
}

Размещение вашего собственного

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

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

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

Есть несколько инструментов, которые могут помочь вам создать репозиторий composer.

Частный Packagist

Private Packagist — это хостируемое или самохостируемое приложение, обеспечивающее хостинг частных пакетов, а также зеркалирование GitHub, Packagist.org и других репозиториев пакетов.

Для получения дополнительной информации посетите Packagist.com.

Satis

Satis — это статический генератор репозиториев composer. Это немного похоже на сверхлегкую статическую файловую версию packagist.

Вы предоставляете ему composer.json с определениями репозиториев, обычно VCS и репозиториев пакетов. Он загрузит все пакеты, required, и сгенерирует packages.json, который будет вашим репозиторием composer.

Дополнительную информацию см. в репозитории satis на GitHub https://github.com/composer/satis и в статье о работе с частными пакетами articles/handling-private-packages.md.

Артефакт

В некоторых случаях нет возможности иметь один из упомянутых ранее типов репозиториев онлайн, даже VCS. Типичным примером может быть обмен библиотеками между организациями с помощью артефактов сборки. Конечно, чаще всего они являются частными. Чтобы использовать эти архивы как есть, можно использовать репозиторий типа artifact с папкой, содержащей ZIP- или TAR-архивы этих частных пакетов:

{
    "repositories": [
        {
            "type": "artifact",
            "url": "path/to/directory/with/zips/"
        }
    ],
    "require": {
        "private-vendor-one/core": "15.6.2",
        "private-vendor-two/connectivity": "*",
        "acme-corp/parser": "10.3.5"
    }
}

Каждый zip-артефакт — это ZIP-архив с composer.json в корневой папке:

unzip -l acme-corp-parser-10.3.5.zip

composer.json
...

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

Путь

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

Например, если у вас следующая структура каталогов в репозитории:

...
├── apps
│   └── my-app
│       └── composer.json
├── packages
│   └── my-package
│       └── composer.json
...

Тогда, чтобы добавить пакет my/package в качестве зависимости в файл apps/my-app/composer.json, можно использовать следующую конфигурацию:

{
    "repositories": [
        {
            "type": "path",
            "url": "../../packages/my-package"
        }
    ],
    "require": {
        "my/package": "*"
    }
}

Если пакет — это локальный репозиторий VCS, версия может быть определена по ветке или тегу, которые в настоящее время выбраны. В противном случае версия должна быть явно определена в файле composer.json пакета. Если версия не может быть определена этими средствами, она предполагается как dev-master.

Когда версия не может быть определена из локального репозитория VCS или когда вы хотите переопределить версию, вы можете использовать параметр versions при объявлении репозитория:

{
    "repositories": [
        {
            "type": "path",
            "url": "../../packages/my-package",
            "options": {
                "versions": {
                    "my/package": "4.2-dev"
                }
            }
        }
    ]
}

Локальный пакет будет связан символической ссылкой, если это возможно, в этом случае на консоли будет отображено Symlinking from ../../packages/my-package. Если символическая ссылка невозможна, пакет будет скопирован. В этом случае на консоли будет отображено Mirrored from ../../packages/my-package.

Вместо стратегии по умолчанию можно принудительно использовать символическую ссылку с помощью параметра "symlink": true или зеркалирование с помощью параметра "symlink": false. Принудительное зеркалирование может быть полезно при развертывании или генерации пакета из монолитного репозитория.

Примечание: В Windows символические ссылки каталогов реализуются с помощью соединений NTFS, так как их могут создавать неадминские пользователи. Зеркалирование всегда будет использоваться в версиях ниже Windows 7 или если proc_open был отключен.

{
    "repositories": [
        {
            "type": "path",
            "url": "../../packages/my-package",
            "options": {
                "symlink": false
            }
        }
    ]
}

Лидирующие тильды расширяются до домашней папки текущего пользователя, и переменные среды анализируются как в обозначениях Windows, так и в обозначениях Linux/Mac. Например, ~/git/mypackage автоматически загрузит клон mypackage из /home/<username>/git/mypackage, эквивалентно $HOME/git/mypackage или %USERPROFILE%/git/mypackage.

Примечание: Пути к репозиториям также могут содержать подстановочные знаки, например, * и ?. Подробности см. в функции PHP glob.

Вы можете настроить способ построения ссылки на dist пакета (которая отображается в файле composer.lock).

Существуют следующие режимы:

none — ссылка всегда будет равна null. Это может помочь уменьшить конфликты файлов блокировки, но снижает ясность относительно того, когда произошло последнее обновление и находится ли пакет в последнем состоянии.
config — ссылка создается на основе хеша composer.json пакета и конфигурации репозитория.
auto (используется по умолчанию) — ссылка создается на основе хеша, как и в config, но если в папке пакета находится репозиторий git, в качестве ссылки используется хеш коммита HEAD.

{
    "repositories": [
        {
            "type": "path",
            "url": "../../packages/my-package",
            "options": {
                "reference": "config"
            }
        }
    ]
}

Отключение Packagist.org

Вы можете отключить репозиторий Packagist.org по умолчанию, добавив это в свой composer.json:

{
    "repositories": [
        {
            "packagist.org": false
        }
    ]
}

Вы можете отключить Packagist.org глобально, используя глобальный флаг конфигурации:

php composer.phar config -g repo.packagist false

← Схема | Настройка →