Skip to content

PACKAGIST.md

Latest commit

 

History

History
112 lines (79 loc) · 4.87 KB

PACKAGIST.md

File metadata and controls

112 lines (79 loc) · 4.87 KB
Raw

Packagist Publishing Guide

The imunify/malware-scanner PHP library is published on Packagist via a public GitHub mirror at cloudlinux/imunify-malware-scanner.

Architecture

GitLab monorepo (php-library/)
        │
        │  CI job triggered by php-lib-X.Y.Z tag
        │  uses git subtree split --prefix=php-library
        ▼
GitHub (cloudlinux/imunify-malware-scanner)
        │
        │  webhook notifies Packagist automatically
        ▼
Packagist (imunify/malware-scanner)

Tag conventions

The library is versioned independently from the product (per DEF-44006). The repo uses two distinct tag prefixes:

Tag pattern Purpose Triggers Packagist sync?
connect-X.Y.Z Product release marker (portal + WP plugin) No
php-lib-X.Y.Z PHP library release Yes

The php-lib- prefix is stripped before pushing to GitHub, so Packagist receives a clean X.Y.Z tag and composer require imunify/malware-scanner:^1.0 keeps working unchanged.

How to release a new library version

  1. Make your changes to php-library/ in the monorepo and merge to main.

    Also bump the version label the portal shows. The library has no version in its source (Packagist derives it from the tag), so the docs pages read the displayed number from a hand-maintained constant. Update PHP_LIBRARY_VERSION in portal/src/version.ts to the new X.Y.Z. If you skip this, the "PHP Library" download badges on the docs pages keep showing the old version.

  2. Create a php-lib-X.Y.Z tag:

    git tag php-lib-1.1.0
git push origin php-lib-1.1.0

  3. The sync:php-library-to-github CI job will automatically:

    • Extract php-library/ into a standalone branch
    • Push it to the GitHub repo's main branch
    • Create a 1.1.0 tag on GitHub (prefix stripped)

  4. Packagist picks up the new version via its GitHub webhook. No manual action needed.

Note: Product tags (connect-X.Y.Z) are safe to push without triggering the sync — useful for marking product releases that don't ship a new library version.

CI/CD setup

Required CI variable

Variable Description
GITHUB_SYNC_TOKEN Fine-grained GitHub PAT with Contents: Read+Write scoped to cloudlinux/imunify-malware-scanner. Store as a masked, protected variable in GitLab > Settings > CI/CD > Variables.

CI jobs

Job Stage Trigger Purpose
sync:php-library-to-github deploy-production Tag php-lib-X.Y.Z Syncs library to GitHub and creates version tag (prefix stripped)
test:php-library-packagist-install test main (auto), staging (manual) Verifies composer require imunify/malware-scanner works
test:php-library-zip-usability test All branches Verifies ZIP download flow works

What gets published

Only the contents of php-library/ are pushed to GitHub:

Included Excluded from composer install --prefer-dist
src/ (library code) tests/ (via .gitattributes)
composer.json phpunit.xml (via .gitattributes)
LICENSE .gitattributes, .gitignore
README.md
tests/ (in repo, not in dist)

Packagist account

Versioning

Follow semver. Tags carry the php-lib- prefix on GitLab; the prefix is stripped on the GitHub push so Packagist sees a clean X.Y.Z:

  • Patch (php-lib-1.0.1 → 1.0.1 on GitHub): Bug fixes, no API changes
  • Minor (php-lib-1.1.0 → 1.1.0 on GitHub): New features, backward compatible
  • Major (php-lib-2.0.0 → 2.0.0 on GitHub): Breaking API changes

Only stable releases are published. Pre-release suffixes (-rc1, -beta, etc.) intentionally do not match the CI regex and will not trigger a Packagist sync.

The composer.json does not contain a version field — Packagist derives versions from git tags.

Troubleshooting

CI job fails with auth error: The GITHUB_SYNC_TOKEN may be expired. Generate a new fine-grained PAT at GitHub > Settings > Personal access tokens, scoped to cloudlinux/imunify-malware-scanner with Contents: Read+Write.

Packagist not updating: Check the webhook at https://github.com/cloudlinux/imunify-malware-scanner/settings/hooks (requires admin access). You can also manually trigger an update from the Packagist package page.

Tag already exists on GitHub: If you need to re-push a tag, delete it first:

git push github :refs/tags/1.1.0
git push github 1.1.0