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

Распространение PHP-пакетов через Packagist

Важно: этот материал покрывает практические шаги, чек-листы и типичные ошибки. Опираемся на стандартные практики Composer и Packagist — без привязки к коммерческим продуктам.

Что вы получите

Пошаговый план от структуры к публикации.
Контрольный чек-лист и критерии приёмки.
Плейбук релиза и обходные пути.
Советы по отладке автозагрузки и совместимости PHP.

Структура пакета и неймспейсы

Перед публикацией пакет должен быть организован в соответствии с PSR-4 и использовать ясный корневой неймспейс. Рекомендуемый формат неймспейса — Author\PackageName.

Пример: неймспейс JSmith\BlogPoster показывает, что разработчик — JSmith, а пакет — BlogPoster.

Создайте директорию /src/ в корне проекта и переместите туда все PHP-файлы. Каждый файл должен начинаться с объявления неймспейса. Пример файла /src/Blogger.php:

Если у вас есть подпапки, неймспейс отражает структуру. Для файла /src/Images/Uploader.php:

Имя класса должно совпадать с именем файла (Uploader.php → class Uploader). Это упрощает навигацию и предотвращает ошибки автозагрузки.

Совет: используйте автотесты и статический анализатор (PHPStan/Psalm) локально, чтобы поймать несоответствия неймспейсов до публикации.

`Создайте composer.json`

В корневой директории создайте файл 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 — обязательно: два сегмента через слэш: php-пользователь/имя-пакета. Первый сегмент обычно совпадает с вашим логином на Packagist/GitHub.
autoload.psr-4 — сопоставляет корневой неймспейс с директорией src/. Обратите внимание на экранирование обратных слэшей в JSON.

Рекомендации:

Указывайте минимальную поддерживаемую версию PHP и, при необходимости, версии зависимостей.
Добавьте разделы “require-dev” и “autoload-dev” для тестов и инструментов разработки.
Указывайте лицензию и homepage — это улучшает доверие пользователей.

`Загрузите репозиторий на GitHub`

Packagist интегрируется с публичными репозиториями (GitHub, GitLab, Bitbucket). Создайте репозиторий и запушьте весь проект, включая /src/ и composer.json.

Простая последовательность команд от терминала (предполагается, что git уже инициализирован и привязан к удалённому origin):

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

Добавьте теги, чтобы пометить версии — Packagist использует теги для отслеживания релизов. Пример пометки v0.1:

git tag 0.1
git push --tags

Совет: используйте семантическое версионирование (MAJOR.MINOR.PATCH) и GitHub Releases для описания изменений.

`Добавьте пакет на Packagist`

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

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

Нажмите Check. Packagist считывает composer.json и доступные теги.
Подтвердите публикацию — через несколько секунд будет доступна страница пакета вида:

https://packagist.org/packages/jsmith/blogposter

Важно: если вы хотите, чтобы Packagist автоматически отслеживал теги и обновления, свяжите аккаунт Packagist с вашим GitHub-аккаунтом через OAuth-приложение Packagist. Это позволит Packagist автоматически обновлять метаданные при пуше тегов.

`Установка и локальная проверка`

Установите Composer, если он ещё не установлен. Пример установки на Unix-подобных системах:

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

Создайте новую директорию проекта и выполните:

composer require jsmith/blogposter

Composer создаст папку /vendor/; внутри вы увидите ваш пакет. Пример простого теста загрузки:

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

`Проверка и отладка автозагрузки`

Типичные проблемы:

Неправильный неймспейс в файле.
Несовпадение имени класса и имени файла (регистр/опечатки).
composer.json содержит неверный mapping в psr-4.

Полезные команды Composer:

composer dump-autoload -o

Эта команда генерирует оптимизированную карту автозагрузки и помогает отловить ошибки.

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

Перед публикацией убедитесь, что пакет соответствует этим критериям:

composer require / устанавливает пакет без ошибок.
Автозагрузка (PSR-4) корректно мапит классы и namespace-ы.
Тесты (если есть) проходят локально и в CI.
В composer.json указан корректный диапазон версий PHP и зависимостей.
Теги соответствуют релизам и имеют понятные описания.

`Чек-лист перед публикацией`

Все PHP-файлы в /src/ имеют корректный namespace.
composer.json присутствует и валиден (composer validate).
README.md содержит инструкции по использованию и примеры.
LICENSE добавлен и выбран корректно.
Минимальная версия PHP указана верно.
Добавлен .gitignore и удалены лишние секреты.
Репозиторий публичен (или вы используете приватный репозиторий и private Packagist).

Команды для проверки:

composer validate
composer test (если настроено)

`Плейбук релиза — быстрый SOP`

Обновите CHANGELOG и README.
Обновите версию в composer.json при необходимости.
Запустите тесты и статический анализ.
Сделайте git commit с понятным сообщением.
Создайте тег: git tag vX.Y.Z
Push: git push && git push –tags
Если Packagist настроен через GitHub OAuth, оно обновит пакет автоматически; иначе вручную отправьте URL на Packagist.

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

Packagist — отличный выбор для публичных пакетов. Но бывают случаи, когда нужен другой путь:

Приватные пакеты внутри компании: используйте Satis, Private Packagist или пакетный прокси (Toran Proxy).
Ограничения безопасности: храните секреты и приватный код во внутреннем реестре.

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

Satis — статичный репозиторий для приватных пакетов.
Private Packagist — коммерческое решение для организаций.
GitHub Packages/GitLab Package Registry — альтернативные реестры, интегрированные с хостом.

`Риски и смягчение`

Риск: публикация секретов (ключей, паролей) в репозитории.

Смягчение: проверьте git history (git-secrets), удалите секреты и перепишите историю перед публикацией.

Риск: несовместимость версий PHP или зависимостей.

Смягчение: указывайте строгие версии в composer.json и тестируйте на нескольких версиях PHP в CI.

Риск: нарушение обратной совместимости при мажорных обновлениях.

Смягчение: придерживайтесь семантического версионирования и документируйте изменения.

`Ментальные модели и эвристики`

“PSR-4 как контракт”: неймспейс ↔ файловая структура — без исключений.
“Малые релизы чаще”: выпускать мелкие патчи быстрее безопаснее, чем большие монолиты.
“Тесты — это входной билет”: без тестов доверие к пакету падает.

`Пример потока действий (Mermaid)`

flowchart TD
  A[Разработать пакет и тесты] --> B[Создать composer.json]
  B --> C[Запушить на GitHub]
  C --> D[Добавить тег релиза]
  D --> E[Отправить URL в Packagist]
  E --> F[Проверить установку через composer require]

`Роли и ответственность`

Автор пакета: отвечает за код, composer.json, тесты, документацию.
Поддерживающий команда: проверяет PR, релизы, багфиксы.
DevOps/CI: настраивает автоматическое тестирование и публикацию (CI-пайплайн может пушить теги).

`Тесты и критерии приёмки`

Проверки для автоматизации в CI:

composer validate — валидность composer.json.
php -l — синтаксическая проверка всех PHP-файлов.
Запуск тестов (PHPUnit/Pest).
Запуск static analysis (PHPStan/Psalm) на уровне, соответствующем политике проекта.

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

Все тесты зелёные.
Нет ошибок автозагрузки.
Тестовая установка через composer require проходит.

`Частые ошибки и как их исправлять`

Пакет не устанавливается: проверьте имя в composer.json и на Packagist.
Класс не найден: проверьте неймспейсы и соответствие имён файлов.
Packagist не видит теги: убедитесь, что теги запушены (git push –tags) и репозиторий публичен.
Неправильная версия PHP: обновите поле “require” в composer.json.

`Советы по улучшению качества пакета`

Пишите README с примерами использования и быстрыми стартами.
Добавьте CI (GitHub Actions, GitLab CI) для автоматических тестов и релизов.
Поддерживайте CHANGELOG и используйте релизные заметки.
Пример использования в README повышает adoption и уменьшает вопросы.

`Краткое резюме`

Публикация пакета на Packagist — это повторяемый процесс: структурируйте код по PSR-4, создайте корректный composer.json, запушьте на GitHub с тегами и добавьте пакет на Packagist. Проверяйте автозагрузку локально и автоматизируйте тесты в CI.

Важно: соблюдайте осторожность с секретами и версионированием. Маленькие, хорошо протестированные релизы безопаснее крупных изменений.

Счастливой публикации — делитесь своими библиотеками с сообществом и следите за обратной связью!

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