README

A PHP client for the Argo CD API. It wraps the REST API in typed service classes and maps every response onto typed model objects, so you get autocompletion and static analysis instead of poking at associative arrays.

PSR-18 / PSR-17 based, bring your own HTTP client or let it discover one.
Token or username/password authentication.
Responses hydrated into typed models via cloudbear/class-mapper.

Requirements

PHP 8.4 or newer
A PSR-18 HTTP client and PSR-17 factories. The client discovers them at runtime via php-http/discovery, so any implementation works. If your project does not already have one, guzzlehttp/guzzle is a convenient choice.

Installation

composer require cloudbear/api-argocd

# If you do not already have a PSR-18 client installed:
composer require guzzlehttp/guzzle

Getting started

You need either an API token or a username and password for your Argo CD instance.

use Cloudbear\ArgoCD\Client;

// With a token
$client = Client::fromToken($token, 'https://argocd.example.com');

// With username and password
$client = Client::fromLogin($username, $password, 'https://argocd.example.com');

$applications = $client->applications()->list();

foreach ($applications as $application) {
    echo $application->metadata->name, "\n";
}

The host may be given with or without a scheme; it is normalized to https:// when none is provided.

Usage

Every resource is reached through an accessor on the client and returns typed models. List endpoints return collection models that are iterable and countable.

// Fetch a single application
$application = $client->applications()->get('guestbook');
echo $application->spec->project;

// Create an application from a model
use Cloudbear\ArgoCD\Models\Applications\Application;

$application = new Application([
    'metadata' => ['name' => 'guestbook'],
    'spec' => [
        'project' => 'default',
        'source' => [
            'repoURL' => 'https://github.com/argoproj/argocd-example-apps',
            'path' => 'guestbook',
            'targetRevision' => 'HEAD',
        ],
        'destination' => ['server' => 'https://kubernetes.default.svc', 'namespace' => 'default'],
    ],
]);

$client->applications()->create($application);

// Sync an application
use Cloudbear\ArgoCD\Models\Applications\ApplicationSync;

$client->applications()->sync('guestbook', new ApplicationSync(['prune' => true]));

// Clusters, projects, repositories, ...
$client->clusters()->list();
$client->projects()->get('default');
$client->repositories()->list();

Most methods accept an optional array $query for query-string parameters, and write endpoints take either a typed model or an array $body, matching the Argo CD API.

Available resources

Accessor	Covers
`$client->accounts()`	Accounts, tokens, `can-i` permission checks
`$client->applications()`	Applications, sync, rollback, resources, manifests, logs
`$client->applicationSets()`	ApplicationSets, generate, resource tree
`$client->certificates()`	Repository certificates
`$client->clusters()`	Clusters, cache invalidation, auth rotation
`$client->gpgKeys()`	GnuPG public keys
`$client->notifications()`	Notification services, templates, triggers
`$client->projects()`	Projects, roles, tokens, sync windows
`$client->repoCreds()`	Repository credentials (read and write)
`$client->repositories()`	Repositories, apps, Helm charts, refs (read and write)
`$client->session()`	Login, logout, user info
`$client->settings()`	Server settings and plugins
`$client->version()`	Server version

Models live under Cloudbear\ArgoCD\Models and mirror the Argo CD API definitions. See the Argo CD API reference for the underlying operations.

Error handling

A non-2xx response throws a Cloudbear\ArgoCD\Exceptions\RequestException. Authentication failures throw Cloudbear\ArgoCD\Exceptions\AuthenticationException.

use Cloudbear\ArgoCD\Exceptions\RequestException;

try {
    $client->applications()->get('does-not-exist');
} catch (RequestException $e) {
    // $e->getMessage(), $e->getCode()
}

The raw PSR-7 response of the last request is available via $client->getLastResponse().

Using a custom HTTP client

The client discovers a PSR-18 client and PSR-17 factories automatically. To supply your own, or to add plugins, pass a configured Builder:

use Cloudbear\ArgoCD\Client;
use Cloudbear\ArgoCD\Credentials\TokenCredentials;
use Cloudbear\ArgoCD\HttpClient\Builder;

$builder = new Builder($myPsr18Client, $myRequestFactory, $myStreamFactory, $myUriFactory);

$client = new Client(new TokenCredentials($token), 'https://argocd.example.com', $builder);

Development

composer install
composer test           # PHPUnit
composer test:coverage  # PHPUnit with a coverage report, needs pcov or Xdebug
composer phpstan        # PHPStan, level 8
composer lint           # PHP-CS-Fixer, writes fixes in place
composer check          # test, phpstan and lint, in order

See CONTRIBUTING.md for the full workflow.

Contributing

This API is partially implemented and contributions are welcome. Please read CONTRIBUTING.md and our Code of Conduct before opening a merge request. For security issues, see SECURITY.md.

License

Released under the MIT License.

cloudbear / api-argocd

Maintainers

Package info

Statistics

Security