Private Packagist API Client

Private Packagist API Client

Requirements

PHP >= 7.2
Guzzle library,

Install

Via Composer:

$ composer require private-packagist/api-client php-http/guzzle6-adapter

Why do you need to require php-http/guzzle6-adapter? We are decoupled from any HTTP messaging client with help by HTTPlug, so you can pick an HTTP client of your choice, guzzle is merely a recommendation.

Basic usage of `private-packagist/api-client` client

<?php

// This file is generated by Composer
require_once __DIR__ . '/vendor/autoload.php';

$client = new \PrivatePackagist\ApiClient\Client();
$client->authenticate('api-token', 'api-secret');
$packages = $client->packages()->all();

From $client object, you can access the full Private Packagist API.

Documentation

Full documentation can be found in the Private Packagist documentation.

Organization

Trigger a full synchronization

$jobs = $client->organization()->sync();

Returns an array of created jobs. One for every synchronization.

Team

List an organization's teams

$teams = $client->teams()->all();

Returns an array of teams.

List all private packages a team has access to

$teamId = 1;
$packages = $client->teams()->packages($teamId);

Returns an array of packages.

Grant a team access to a list of private packages

$teamId = 1;
$packages = $client->teams()->addPackages($teamId, ['acme-website/package']);

Returns an array of packages.

Remove access for a package from a team

$teamId = 1;
$packages = $client->teams()->removePackage($teamId, 'acme-website/package');

Customer

List an organization's customers

$customers = $client->customers()->all();

Returns an array of customers.

Show a customer

$customerId = 42;
$customer = $client->customers()->show($customerId);
// or
$customerUrlName = 'customer-url-name';
$customer = $client->customers()->show($customerUrlName);

Returns a single customer.

Create a customer

$customer = $client->customers()->create('New customer name');
// or
$customer = $client->customers()->create('New customer name', false, 'customer-url-name', 'beta');

Returns the customer.

Edit a customer

$customerId = 42;
$customerData = [
    'name' => $name,
    'urlName' => 'customer',
    'accessToVersionControlSource' => false,
    'minimumAccessibleStability' => 'beta',
];
$customer = $client->customers()->edit($customerId, $customerData);

Returns the customer.

Delete a customer

$customerId = 42;
$client->customers()->remove($customerId);

Enable a customer

$customerId = 42;
$customer = $client->customers()->enable($customerId);

Disable a customer

$customerId = 42;
$customer = $client->customers()->disable($customerId);

List a customer's packages

$customerId = 42;
$packages = $client->customers()->listPackages($customerId);

Returns an array of customer packages.

Grant a customer access to a package or edit the limitations

$customerId = 42;
$packages = [
    [
        'name' => 'acme-website/package',
        'versionConstraint' => '^1.0 | ^2.0', // optional version constraint to limit updates the customer receives
        'expirationDate' => (new \DateTime())->add(new \DateInterval('P1Y'))->format('c'), // optional expiration date to limit updates the customer receives
        'minimumAccessibleStability' => 'beta', // optional stability to restrict customers to specific package version stabilities like alpha, beta, or RC
    ],
];
$packages = $client->customers()->addOrEditPackages($customerId, $packages);

Returns an array of all added or edited customer packages.

Revoke access to a package from a customer

$customerId = 42;
$packageName = 'acme-website/package';
$client->customers()->removePackage($customerId, $packageName);

Regenerate a customer's Composer repository token

$customerId = 42;
$confirmation = [
    'IConfirmOldTokenWillStopWorkingImmediately' => true,
];
$composerRepository = $client->customers()->regenerateToken($customerId, $confirmation);

Returns the edited Composer repository.

Subrepository

List an organization's subrepositories

$subrepositories = $client->subrepositories()->all();

Returns an array of subrepositories.

Show a subrepository

$subrepositoryName = 'subrepository';
$subrepository = $client->subrepositories()->show($subrepositoryName);

Returns a single subrepository.

Create a subrepository

$subrepository = $client->subrepositories()->create('New subrepository name');

Returns the subrepository.

Delete a subrepository

$subrepositoryName = 'subrepository';
$client->subrepositories()->remove($subrepositoryName);

List a subrepositories's teams

$subrepositoryName = 'subrepository';
$teams = $client->subrepositories()->listTeams($subrepositoryName);

Returns an array of subrepositories teams.

Add a team to a subrepository or edit the permission

$subrepositoryName = 'subrepository';
$teams = [
    [
        'id' => 12,
        'permission' => 'owner',
    ],
];
$teams = $client->subrepositories()->addOrEditTeams($subrepositoryName, $teams);

Returns an array of added subrepository teams.

Remove a team from a subrepository

$subrepositoryName = 'subrepository';
$teamId = 12;
$client->subrepositories()->removeTeam($subrepositoryName, $teamId);

List a subrepositories's packages

$subrepositoryName = 'subrepository';
$packages = $client->subrepositories()->packages()->all($subrepositoryName);

Returns an array of subrepositories packages.

Show a subrepository package

$subrepositoryName = 'subrepository';
$package = $client->subrepositories()->packages()->show($subrepositoryName, 'acme-website/package');

Returns the package.

Create a vcs package in a subrepository

$subrepositoryName = 'subrepository';
$job = $client->subrepositories()->packages()->createVcsPackage($subrepositoryName, 'https://github.com/acme-website/package');

Returns a new job.

Create a vcs package with credentials in a subrepository

$subrepositoryName = 'subrepository';
$credentialId = 42;
$job = $client->subrepositories()->packages()->createVcsPackage($subrepositoryName,'https://github.com/acme-website/package', $credentialId);

Returns a new job.

Create a custom package in a subrepository

$subrepositoryName = 'subrepository';
$packageDefinition = '{...}';
$job = $client->subrepositories()->packages()->createCustomPackage($subrepositoryName, $packageDefinition);

Returns a new job.

Create a custom package with credentials in a subrepository

$subrepositoryName = 'subrepository';
$packageDefinition = '{...}';
$credentialId = 42;
$job = $client->subrepositories()->packages()->createCustomPackage($subrepositoryName, $packageDefinition, $credentialId);

Returns a new job.

Edit a vcs package in a subrepository in a subrepository

$subrepositoryName = 'subrepository';
$job = $client->subrepositories()->packages()->editVcsPackage($subrepositoryName, 'acme-website/package', 'https://github.com/acme-website/package');

Returns a new job.

Edit a custom package in a subrepository

$subrepositoryName = 'subrepository';
$packageDefinition = '{...}';
$job = $client->subrepositories()->packages()->editCustomPackage($subrepositoryName, 'acme-website/package', $packageDefinition);

Returns a new job.

Delete a package from a subrepository

$subrepositoryName = 'subrepository';
$client->subrepositories()->packages()->remove($subrepositoryName, 'acme-website/package');

List all dependents of a subrepository package

$subrepositoryName = 'subrepository';
$client->subrepositories()->packages()->listDependents($subrepositoryName, 'acme-website/package');

Returns a list of packages.

List a subrepositories's authentication tokens

$subrepositoryName = 'subrepository';
$tokens = $client->subrepositories()->listTokens($subrepositoryName);

Returns an array of authentication tokens.

Create a subrepository authentication token

$subrepositoryName = 'subrepository';
$data = [
  'description' => 'Subrepository Token',
  'access' => 'read',
];
$token = $client->subrepositories()->createToken($subrepositoryName, $data);

Returns the authentication token.

Delete a subrepository authentication token

$subrepositoryName = 'subrepository';
$tokenId = 33;
$client->subrepositories()->removeToken($subrepositoryName, $tokenId);

Regenerate a subrepository authentication token

$subrepositoryName = 'subrepository';
$tokenId = 33;
$confirmation = [
    'IConfirmOldTokenWillStopWorkingImmediately' => true,
];
$token = $client->subrepositories()->regenerateToken($subrepositoryName, $confirmation);

Returns the authentication token.

List a subrepositories's mirrored repositories

$subrepositoryName = 'subrepository';
$mirroredRepositories = $client->subrepositories()->mirroredRepositories()->all($subrepositoryName);

Returns an array of mirrored repositories.

Show a mirrored repository

$subrepositoryName = 'subrepository';
$mirroredRepositoryId = 42;
$mirroredRepository = $client->subrepositories()->mirroredRepositories()->show($subrepositoryName, $mirroredRepositoryId);

Returns the mirrored repository.

Add mirrored repositories to a subrepository

$subrepositoryName = 'subrepository';
$mirroredRepositoriesToAdd = [
    ['id' => 12, 'mirroringBehavior' => 'add_on_use'],
];
$mirroredRepository = $client->subrepositories()->mirroredRepositories()->add($subrepositoryName, $mirroredRepositoriesToAdd);

Returns a list of added mirrored repositories.

Edit the mirroring behaviour of mirrored repository in a subrepository

$subrepositoryName = 'subrepository';
$mirroredRepositoryId = 42;
$mirroredRepository = $client->subrepositories()->mirroredRepositories()->create($subrepositoryName, $mirroredRepositoryId, 'add_on_use');

Returns the edited mirrored repository.

Delete a mirrored repository from a subrepository

$subrepositoryName = 'subrepository';
$mirroredRepositoryId = 42;
$client->subrepositories()->mirroredRepositories()->remove($subrepositoryName, $mirroredRepositoryId);

List all mirrored packages from a mirrored repository in a subrepository

$subrepositoryName = 'subrepository';
$mirroredRepositoryId = 42;
$packages = $client->subrepositories()->mirroredRepositories()->listPackages($subrepositoryName, $mirroredRepositoryId);

Returns an array of packages.

Add mirrored packages from one mirrored repository to a subrepository

$subrepositoryName = 'subrepository';
$mirroredRepositoryId = 42;
$packages = [
    'acme/cool-lib
];
$jobs = $client->subrepositories()->mirroredRepositories()->addPackages($subrepositoryName, $mirroredRepositoryId, $packages);

Returns an array of jobs.

Remove all mirrored packages from one mirrored repository in a subrepository

$subrepositoryName = 'subrepository';
$mirroredRepositoryId = 42;
$client->subrepositories()->mirroredRepositories()->removePackages($subrepositoryName, $mirroredRepositoryId);

Package

List an organization's packages

$filters = [
    'origin' => \PrivatePackagist\ApiClient\Api\Packages::ORIGIN_PRIVATE, // optional filter to only receive packages that can be added to customers,
    'security-issue-state' => \PrivatePackagist\ApiClient\Api\SecurityIssues::STATE_OPEN, // optional filter to filter packages with open security issues,
];
$packages = $client->packages()->all($filters);

Returns an array of packages.

Show a package

$package = $client->packages()->show('acme-website/package');

Returns the package.

Create a vcs package

$job = $client->packages()->createVcsPackage('https://github.com/acme-website/package');

Returns a new job.

Create a vcs package with credentials

$credentialId = 42;
$job = $client->packages()->createVcsPackage('https://github.com/acme-website/package', $credentialId);

Returns a new job.

Create a vcs package with a specific type

$job = $client->packages()->createVcsPackage('https://github.com/acme-website/package', null, 'git');

Returns a new job.

Create a custom package

$packageDefinition = '{...}';
$job = $client->packages()->createCustomPackage($packageDefinition);

Returns a new job.

Create a custom package with credentials

$packageDefinition = '{...}';
$credentialId = 42;
$job = $client->packages()->createCustomPackage($packageDefinition, $credentialId);

Returns a new job.

Edit a vcs package

$job = $client->packages()->editVcsPackage('acme-website/package', 'https://github.com/acme-website/package');

Returns a new job.

Edit a custom package

$packageDefinition = '{...}';
$job = $client->packages()->editCustomPackage('acme-website/package', $packageDefinition);

Returns a new job.

Delete a package

$client->packages()->remove('acme-website/package');

List all dependents of a package

$client->packages()->listDependents('acme-website/package');

Returns a list of packages.

List all customers with access to a package

$client->packages()->listCustomers('acme-website/package');

Returns a list of customers with access to the package.

List all security issues of a package

$filters = [
    'security-issue-state' => \PrivatePackagist\ApiClient\Api\SecurityIssues::STATE_OPEN,
];
$client->packages()->listSecurityIssues('acme-website/package', $filters);

Returns a list of security issues.

Create an artifact package file

$fileName = 'package1.zip'; // your package archive artifact containing a valid composer.json in root directory
$file = file_get_contents($fileName);
$client->packages()->artifacts()->create($file, 'application/zip', $fileName);

Create an artifact package

$fileName = 'package1.zip';
$file = file_get_contents($fileName);
$response = $client->packages()->artifacts()->create($file, 'application/zip', $fileName);
$artifactId = $response['id'];
$client->packages()->createArtifactPackage([$artifactId]);

Add an artifact file to an existing package

$packageName = 'acme/artifact';
$fileName = 'package1.zip';
$file = file_get_contents($fileName);
$client->packages()->artifacts()->add($packageName, $file, 'application/zip', $fileName);

Update or replace artifact files of a package

// in case you want to replace the artifact file with a newly uploaded one
// 1. get current artifact ids
$result = $client->packages()->artifacts()->showPackageArtifacts('acme-website/package');
$artifactIds = array_column($result, 'id'); // [41, 42]

// 2. upload the new artifact file
$fileName = 'package1.zip';
$file = file_get_contents($fileName);
$response = $client->packages()->artifacts()->create($file, 'application/zip', $fileName);
$newArtifactId = $response['id'];

// 3. let's say we don't want to have the artifact file id = 41 and use the newly uploaded file instead
$artifactIds = array_shift($artifactIds);
$artifactIds[] = $newArtifactId;
$client->packages()->editArtifactPackage('acme-website/package', $artifactIds);

Credential

List an organization's credentials

$credentials = $client->credentials()->all();

Returns an array of credentials.

Show a credential

$credentialId = 42;
$credential = $client->credentials()->show($credentialId);

Returns the credential.

Create a credential

$type = \PrivatePackagist\ApiClient\Api\Credentials::TYPE_HTTP_BASIC;
$credential = $client->credentials()->create('ACME http auth', $type, 'acme-website.com', 'username', 'password');

Returns the new credential.

Edit a credential

$credentialId = 42;
$type = \PrivatePackagist\ApiClient\Api\Credentials::TYPE_HTTP_BASIC;
$credential = $client->credentials()->edit($credentialId, $type, 'username', 'password');

Returns the edited credential.

Delete a credential

$credentialId = 42;
$client->credentials()->remove($credentialId);

Mirrored Repository

List an organization's mirrored repositories

$mirroredRepositories = $client->mirroredRepositories()->all();

Returns an array of mirrored repositories.

Show a mirrored repository

$mirroredRepositoryId = 42;
$mirroredRepository = $client->mirroredRepositories()->show($mirroredRepositoryId);

Returns the mirrored repository.

Create a mirrored repository

$mirroredRepository = $client->mirroredRepositories()->create('Mirrored Repository', 'https://composer.example.com', 'add_on_use', 543);

Returns the new mirrored repository.

Edit a mirrored repository

$mirroredRepositoryId = 42;
$mirroredRepository = $client->mirroredRepositories()->create($mirroredRepositoryId, 'Mirrored Repository', 'https://composer.example.com', 'add_on_use', 543);

Returns the edited mirrored repository.

Delete a mirrored repository

$mirroredRepositoryId = 42;
$client->mirroredRepositories()->remove($mirroredRepositoryId);

List all mirrored packages from one repository

$mirroredRepositoryId = 42;
$packages = $client->mirroredRepositories()->listPackages($mirroredRepositoryId);

Returns an array of packages.

Add mirrored packages from one repository

$mirroredRepositoryId = 42;
$packages = [
    'acme/cool-lib
];
$jobs = $client->mirroredRepositories()->addPackages($mirroredRepositoryId, $packages);

Returns an array of jobs.

Remove all mirrored packages from one repository

$mirroredRepositoryId = 42;
$client->mirroredRepositories()->removePackages($mirroredRepositoryId);

Job

Show a job

$job = $client->jobs()->show($jobId);

Returns the job.

Wait for a job to finish

This will periodically poll the job status until the job either finished or the maximum wait time was reached

$numberOfSecondsToWait = 180;
$jobHelper = new \PrivatePackagist\ApiClient\JobHelper($client);
try {
    $job = $jobHelper->waitForJob($jobId, $numberOfSecondsToWait);
} catch (\PrivatePackagist\ApiClient\Exception\JobTimeoutException $e) {
    // Job didn't finish within the specified time
} catch (\PrivatePackagist\ApiClient\Exception\JobErrorException $e) {
    // Job finished with an error. See the message for more information
    echo $e->getMessage();
}

Returns the job.

Security Issue

List an organization's security issues

$filters = [
    'security-issue-state' => \PrivatePackagist\ApiClient\Api\SecurityIssues::STATE_OPEN, // optional filter to filter packages with open security issues,
];
$packages = $client->securityIssues()->all($filters);

Returns an array of security issues.

Magento legacy keys

List all legacy keys for a customer

$customerId = 42;
$legacyKeys = $client->customers()->magentoLegacyKeys()->all($customerId);

Returns a list of Magento legacy keys.

Create a new legacy keys for a customer

$legacyKey = $client->customers()->magentoLegacyKeys()->create($customerId, $publicKey, $privateKey);

Returns the new Magento legacy key.

Delete a legacy keys from a customer

$client->customers()->magentoLegacyKeys()->remove($customerId, $publicKey);

Validate incoming webhook payloads

When you create or update a webhook in Private Packagist an optional secret can be set. This secret gets used to create a signature which is sent with each request in the headers as Packagist-Signature. The secret and signature can then be used on your server to validate that the request was made by Private Packagist. If no secret is set then no signature is sent.

$request = /** any Psr7 request */;
$secret = 'webhook-secret';
$webhookSignature = new \PrivatePackagist\ApiClient\WebhookSignature($secret);
$requestSignature = $request->hasHeader('Packagist-Signature') ? $request->getHeader('Packagist-Signature')[0] : null; 
$webhookSignature->validate($requestSignature, (string) $request->getBody());

License

private-packagist/api-client is licensed under the MIT License

We have a fully operational private packagist running. Adding packages through composer or adding them manual works like a charm.

We are using your package (packagist/private-packagist-api-client) to communicate with the private packagist's API.

However, when using this API, we get an error when using specific API endpoints. More specifically, the GET /api/ackages/{packageName} and the POST /api/packages/{packageName}.

Given this piece of example code:

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

$privatePackagistUrl = '';
$apiToken = '';
$apiSecret = '';

$client = new \PrivatePackagist\ApiClient\Client(null, $privatePackagistUrl);
$client->authenticate($apiToken, $apiSecret);
$packages = $client->packages()->all();
/**
 * print_r($packages);
 * (
 *     [0] => Array
 *         (
 *             [name] => symfony/console
 *             [origin] => public-proxy
 *             [credentials] => 
 *             [links] => Array
 *                 (
 *                     [self] => /api/packages/symfony/console/
 *                 )
 * 
 *         )
 * 
 * )
 */

$client = new \PrivatePackagist\ApiClient\Client(null, $privatePackagistUrl);
$client->authenticate($apiToken, $apiSecret);
$package = $client->packages()->show('symfony/console');
// Fatal error: Uncaught PrivatePackagist\ApiClient\Exception\RuntimeException: Access Denied.

This results in a fatal error:

PHP Fatal error:  Uncaught PrivatePackagist\ApiClient\Exception\RuntimeException: Access Denied. in /[dir]/vendor/private-packagist/api-client/src/HttpClient/Plugin/ExceptionThrower.php:41
Stack trace:
#0 /[dir]/vendor/php-http/httplug/src/Promise/HttpFulfilledPromise.php(34): PrivatePackagist\ApiClient\HttpClient\Plugin\ExceptionThrower->PrivatePackagist\ApiClient\HttpClient\Plugin\{closure}(Object(GuzzleHttp\Psr7\Response))
#1 /[dir]/vendor/private-packagist/api-client/src/HttpClient/Plugin/ExceptionThrower.php(42): Http\Client\Promise\HttpFulfilledPromise->then(Object(Closure))
#2 /[dir]/vendor/php-http/client-common/src/Pl in /[dir]/vendor/private-packagist/api-client/src/HttpClient/Plugin/ExceptionThrower.php on line 41

The response returned by the API is:

string(109) "{"status":"error","message":"Access Denied.","documentationUrl":"[packagist-url]\/docs\/api"}"

The API credentials I use are good, the first API call (and other API calls for that matter) give proper responses. It is the show() and editVcsPackage() methods that fail.

I suspect it has something to do with the slash in the packageName, but escaping this did not help.

Could you perhaps see what I am doing wrong, or confirm that this is a bug?

Using packageName in the API results in "Access Denied" error

opened by QassaDevelopers 3

Move from `php-http/client-implementation` to `psr/http-client-implementation`

As per https://github.com/php-http/httplug

New client implementations and consumers should use the PSR-18 interfaces directly. In the long term, we expect PSR-18 to completely replace the need for HTTPlug.

For projects using guzzlehttp/guzzle in version 7 or higher this removes the need to also require php-http/guzzle7-adapter.

opened by Kingdutch 2
Fix passing null to parameter of type string

Passing null to internal PHP functions, with argument type of string is deprecated in PHP 8.1.

This can be easily fixed by supplying empty strings instead.

Closes #47

opened by janmartendeboer 1
Fully automate dev setup with Gitpod

This commit implements a fully-automated development setup using Gitpod.io, an online IDE for GitHub and GitLab that enables Dev-Environments-As-Code. This makes it easy for anyone to get a ready-to-code workspace for any branch, issue or pull request almost instantly with a single click.

opened by strausmann 1
PSR: replace php-http/client-implementation with psr/http-client-implementation

Resolves https://github.com/packagist/private-packagist-api-client/issues/52

~Still need to confirm that this doesn't remove support for any of the most popular HTTP clients.~ Looks good

opened by glaubinix 0

RequestSignature::normalizeParameters uses deprecated invocation

http_build_query(): Passing null to parameter #2 ($numeric_prefix) of type string is deprecated

In src/HttpClient/Plugin/RequestSignature.php on line 87.

Affected version: 1.25.0 PHP version: 8.1.0

Context

private function normalizeParameters(array $params)
{
    uksort($params, 'strcmp');

    return http_build_query($params, null, '&', PHP_QUERY_RFC3986);
}