Packagist: как опубликовать PHP-пакет

Иллюстрация: распространение PHP-пакетов через Packagist

TL;DR

Packagist — де-факто централизованный репозиторий для PHP-пакетов. Подготовьте структуру пакета с PSR-4 неймспейсом, добавьте корректный composer.json, запушьте код и теги в GitHub и отправьте ссылку на страницу Submit Package. После публикации любой сможет установить пакет одной командой composer require.

Зачем это важно

Публикация на Packagist делает ваш пакет доступным для миллионов проектов, облегчает управление зависимостями и автоматизирует автозагрузку через Composer.

Структура пакета: как правильно организовать проект

Прежде чем публиковать, убедитесь, что пакет организован по современным стандартам PHP и использует неймспейсы (namespaces). Это упрощает автозагрузку и уменьшает вероятность конфликтов имён.

Ключевые рекомендации:

Выберите корневой неймспейс в формате Author\PackageName (например, JSmith\BlogPoster). Название автора обычно совпадает с вашим именем пользователя на Packagist/GitHub.
Поместите исходники в каталог src/.
В начале каждого PHP-файла объявите namespace, соответствующий пути внутри src/.
Имя класса должно совпадать с именем файла (Uploader.php → class Uploader).

Пример файла /src/Images/Uploader.php:

Важно: namespace соответствует структуре каталогов. Если класс находится в src/Images, неймспейс включает Images.

`Регистрация аккаунта на Packagist`

Зарегистрируйте аккаунт на https://packagist.org, если у вас его ещё нет. Рекомендуется использовать имя пользователя, совпадающее с тем, что вы указали в корневом неймспейсе и в composer.json (первый сегмент имени пакета). Это облегчает узнаваемость и управление пакетами.

Ничего публиковать не нужно сразу — аккаунт пригодится при синхронизации и приёмке прав на пакет.

`Создаём composer.json`

В корне проекта создайте файл composer.json. Это основной мета-файл пакета: в нём задаются имя пакета, требования к PHP, лицензия, автозагрузка и т.д.

Пример composer.json:

{
  "name": "jsmith/blogposter",
  "description": "An excellent blog posting package...",
  "type": "package",
  "homepage": "https://yourdomain.com",
  "license": "MIT",
  "require": {
    "php": ">=8.0.0"
  },
  "autoload": {
    "psr-4": {
      "JSmith\\BlogPoster\\": "src/"
    }
  }
}

На что обратить внимание:

“name”: должно быть в формате “vendor/package” — vendor обычно совпадает с вашим именем пользователя на Packagist/GitHub.
“autoload”: используйте psr-4 и укажите соответствие неймспейса и каталога src/.
Укажите минимальную версию PHP и лицензию.

Короткое определение: PSR-4 — это стандарт автозагрузки классов, где namespace ↔ путь в файловой системе.

`Загрузка кода в GitHub`

Packagist интегрируется с публичными репозиториями GitHub, поэтому разместите проект в репозитории.

Базовые команды для загрузки всего проекта в новый репозиторий:

git add ./*
git commit -m "Initial commit"
git push -u origin master

После загрузки добавьте тег версии — Packagist использует теги как релизы:

git tag 0.1
git push --tags

Совет: используйте семантическое версионирование (semver) — например v0.1.0, v1.2.3. Semver помогает пользователям понять уровень совместимости.

`Публикация на Packagist`

Перейдите на страницу Submit Package на Packagist и вставьте URL репозитория, например:

https://github.com/jsmith/blogposter.git

Нажмите Check — Packagist скачает composer.json, обнаружит теги и создаст карточку пакета. После подтверждения пакет будет доступен по адресу https://packagist.org/packages/jsmith/blogposter.

Если вы хотите, чтобы Packagist автоматически обновлял информацию при пуше тега, подключите интеграцию с GitHub (webhook), которая предложена на Packagist после регистрации.

`Установка пакета через Composer`

Проверим установку. Если Composer ещё не установлен, можно установить его глобально (пример для Unix-систем):

sudo curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

Теперь в новой директории выполните:

composer require jsmith/blogposter

Composer загрузит зависимости и создаст каталог vendor/, где будет ваш пакет. Пример использования из тестового скрипта:

`Релиз и поддержка пакета`

После публикации поддерживайте README, тесты и CI (Continuous Integration). Поддержка включает:

Обновление composer.json при изменении требований.
Публикация новых тегов с релизами.
Ответы на issues и прием pull request’ов.

Хорошая практика — настраивать GitHub Actions или другой CI для автоматического запуска тестов, проверки статического анализа и генерации релизов.

`Альтернативы и когда Packagist не подходит`

Packagist — идеален для публичных пакетов, но есть сценарии, когда стоит выбрать другое решение:

Частные зависимостии: используйте приватный репозиторий Composer, Satis, Toran Proxy или менеджеры артефактов (JFrog Artifactory, Sonatype Nexus).
Ограниченные сети без доступа к GitHub: размещайте архивы на внутреннем хранилище и указывайте их как репозиторий в composer.json.
Очень крупные корпоративные каталоги: предпочтительней централизованный артефакт-репозиторий с правами доступа.

`Когда публикация может провалиться`

composer.json некорректен (синтаксическая ошибка или неверные поля).
Неймспейсы не совпадают с путями файлов, автозагрузка ломается.
Теги не были запушены в репозиторий, Packagist не видит релизов.
Репозиторий приватный и Packagist не имеет доступа.

Вариант отладки: посмотреть лог Packagist на странице пакета и исключения composer при локальной установке.

`Мини-методология релизов (быстрый процесс)`

Обновите CHANGELOG и README.
Увеличьте версию согласно семантическому версионированию.
Запустите все тесты и статический анализ.
Создайте тег (например v1.0.0) и запушьте теги.
Убедитесь, что Packagist обновился (или вручную отправьте webhook).
Закройте связанные issue и объявите релиз.

`Чек-лист перед публикацией (для автора)`

В проекте есть README с примером использования.
composer.json валиден и содержит psr-4 autoload.
Все классы и неймспейсы соответствуют структуре каталогов.
Запущены тесты и CI проходит.
Добавлен LICENSE (желательно открытая лицензия: MIT, BSD, Apache).
Репозиторий содержит теги релизов.
В README указана совместимая версия PHP.

`Критерии приёмки`

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

`Безопасность и приватность`

Не включайте секреты, API-ключи или приватные файлы в репозиторий и composer.json.
Проверьте зависимости на уязвимости (composer audit или инструменты SCA).
Если пакет обрабатывает персональные данные, документируйте, какие данные собираются и как они обрабатываются. Учитывайте требования GDPR, если ваш пакет будет использоваться в ЕС.

`Краткий глоссарий (1 строка)`

Composer — менеджер зависимостей для PHP.
Packagist — центральный реестр публичных PHP-пакетов.
PSR-4 — стандарт автозагрузки классов в PHP.
Semver — семантическое версионирование.

`Частые ошибки и способы их устранения`

Ошибка: Class not found — проверьте соответствие namespace и пути, убедитесь, что autoload настроен.
Packagist не видит новый релиз — проверьте, что теги запушены и что репозиторий публичен.
composer require падает с ошибкой парсинга composer.json — валидируйте файл через composer validate.

`Социальный предпросмотр (рекомендация)`

Заголовок: “Packagist: быстрое руководство по публикации PHP-пакета”. Описание: “Подготовьте пакет, настройте composer.json и разместите на Packagist — установка одной командой.”

`FAQ`

`Как указать приватный репозиторий в composer.json?`

Добавьте блок “repositories” в composer.json с типом “vcs” и ссылкой на ваш приватный репозиторий или настройте Composer auth.json для доступа.

`Нужен ли отдельный аккаунт Packagist, если у меня есть GitHub?`

Да, Packagist использует собственный аккаунт. Рекомендуется связать его с GitHub для автоматических обновлений и управления правами.

`Итог и следующие шаги`

Теперь вы знаете, как подготовить пакет, создать composer.json, залить проект на GitHub, пометить релиз тегом и опубликовать пакет на Packagist. Настройте CI, добавьте тесты и поддерживайте пакет — так вы привлечёте пользователей и сделаете свой код стабильным и легко подключаемым.

Вдохновляйтесь, развивайте пакет, и делитесь им с сообществом.