README

adachsoft/packagist-releaser-lib coordinates the validation and publication of PHP packages to Packagist.

The library resolves package metadata, validates a release, detects whether the package already exists on Packagist, and creates or updates the package accordingly.

Requirements

PHP 8.3 or newer
A Git repository containing the package to release
A valid composer.json
A Packagist username and API token for non-dry-run releases

Installation

Install the library with Composer:

composer require adachsoft/packagist-releaser-lib

Quick start

<?php

declare(strict_types=1);

use AdachSoft\PackagistReleaserLib\Release\Dto\ReleasePackageRequestDto;
use AdachSoft\PackagistReleaserLib\Release\Factory\PackagistReleaserFactory;

$releaser = PackagistReleaserFactory::create(
    username: (string) getenv('PACKAGIST_USERNAME'),
    apiToken: (string) getenv('PACKAGIST_API_TOKEN'),
);

$result = $releaser->release(
    new ReleasePackageRequestDto(
        repositoryPath: __DIR__,
    ),
);

printf(
    "Package %s was %s.\n",
    $result->packageName,
    $result->action->value,
);

The default request configuration resolves the following values automatically:

the package name from composer.json;
the repository URL from the origin Git remote;
the release version through the release validation process;
the changelog from CHANGELOG.md.

All values can be supplied explicitly when required:

$request = new ReleasePackageRequestDto(
    repositoryPath: '/path/to/package',
    repositoryUrl: 'https://github.com/vendor/package.git',
    packageName: 'vendor/package',
    version: '1.2.3',
    changelogPath: 'CHANGELOG.md',
);

Dry-run mode

Use dryRun: true to validate and resolve the release without sending a mutating request to Packagist:

$result = $releaser->release(
    new ReleasePackageRequestDto(
        repositoryPath: __DIR__,
        dryRun: true,
    ),
);

if ($result->isDryRun()) {
    echo "The release was simulated; Packagist was not modified.\n";
}

A dry run still checks whether the package exists and reports the action that would be performed (create or update).

Release result

release() returns a PackageReleaseResultDto containing:

packageName - the Composer package name;
repositoryUrl - the repository URL used for publication;
version - the release version;
action - ReleaseActionEnum::CREATE or ReleaseActionEnum::UPDATE;
dryRun - whether the operation was simulated;
validationResult - the complete release validation result.

Convenience methods are available for common checks:

if ($result->wasCreated()) {
    echo "A new Packagist package was created.\n";
}

if ($result->wasUpdated()) {
    echo "The existing Packagist package was updated.\n";
}

$data = $result->toArray();

Release workflow

The release process consists of the following stages:

Resolve and validate repository metadata.
Read the package name from composer.json when it is not supplied.
Read and normalize the origin Git remote URL when it is not supplied.
Validate the release using adachsoft/release-validator.
Check whether the package exists on Packagist.
Create a new package or update the existing package.
Return the validation and publication result.

Validation uses a fail-fast approach. If the release is invalid, the publishing step is not executed.

Custom clients and dependencies

Use createWithCustomClients() when the Packagist API client or release validation facade must be supplied by the application:

use AdachSoft\PackagistApiClient\PackagistApiClientInterface;
use AdachSoft\PackagistReleaserLib\Release\Factory\PackagistReleaserFactory;
use AdachSoft\ReleaseValidator\Contract\ReleaseValidationFacadeInterface;

/** @var PackagistApiClientInterface $packagistApiClient */
/** @var ReleaseValidationFacadeInterface $releaseValidationFacade */
$releaser = PackagistReleaserFactory::createWithCustomClients(
    $packagistApiClient,
    $releaseValidationFacade,
);

For more detailed dependency customization, use PackagistReleaserBuilder to replace individual components such as the metadata resolver, validation runner, or publisher.

Exceptions

The library exposes domain-specific exceptions for invalid input and failed release stages, including:

InvalidPackageNameException;
InvalidRepositoryPathException;
InvalidRepositoryUrlException;
InvalidVersionFormatException;
ComposerJsonReadException;
GitRemoteUrlResolutionException;
PackageMetadataResolutionException;
ReleaseValidationFailedException;
PackagistPublishFailedException.

All library exceptions implement PackagistReleaserExceptionInterface where applicable.

Architecture

The code is organized by feature:

Common - value objects, enums, and shared exception contracts;
Metadata - package and repository metadata resolution;
Validation - release validation integration;
Publishing - Packagist package detection and publication;
Release - public API, orchestration, DTOs, factories, and builders.

The main public entry points are:

PackagistReleaserFactory;
PackagistReleaserBuilder;
PackagistReleaserInterface;
ReleasePackageRequestDto;
PackageReleaseResultDto.

Development

Install development dependencies:

composer install

Run the test suite:

vendor/bin/phpunit

Run static analysis:

vendor/bin/phpstan analyse src tests

License

This library is distributed under the MIT License. See LICENSE for details.

adachsoft / packagist-releaser-lib

Package info

Security

Statistics