Skip to content

feat: Initial ArgoCD PHP Client Structure and Core Services #1150

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions AI.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# AI-Assisted Development Context: PHP ArgoCD API Client

This document provides context on the development process of this PHP client for the ArgoCD API, which was significantly assisted by an AI agent named Jules.

## Project Goal

The primary goal of this project was to refactor an existing PHP client library originally designed for the GitHub API (KnpLabs/php-github-api) and adapt it to become a fully functional client for the ArgoCD REST API.

## Development Process

The development process involved a collaborative effort between a human developer and the AI agent, Jules. Key aspects of this process include:

* **Initial Request:** The human developer provided an issue statement outlining the need to fork the GitHub library, study its structure, and then refactor it to implement ArgoCD's OpenAPI specification (`https://raw.githubusercontent.com/argoproj/argo-cd/master/assets/swagger.json`).
* **Codebase Analysis:** Jules explored the existing GitHub client's codebase using tools to list files and read their content to understand its architecture and patterns.
* **OpenAPI Analysis:** Jules fetched and analyzed the ArgoCD OpenAPI specification to understand its endpoints, data structures, and service organization.
* **Planning:** Based on the analysis, Jules created a detailed, multi-step plan to execute the refactoring. This plan was reviewed and approved by the human developer.
* **Iterative Implementation:** Jules executed the plan step-by-step by delegating specific, actionable tasks to a "Worker" agent. These tasks included:
* Creating new directory structures.
* Initializing `composer.json` and managing dependencies.
* Adapting core client classes (`Client.php`, `HttpClient/Builder.php`, `Api/AbstractApi.php`).
* Implementing exception handling.
* Generating PHP model classes based on OpenAPI definitions.
* Implementing API service classes (e.g., `SessionService.php`, `AccountService.php`) with methods corresponding to ArgoCD API operations.
* **Feedback Incorporation:** The human developer provided feedback at various stages (e.g., on directory structure, PHP version constraints), and Jules updated the plan and execution accordingly.

## Current State

As of the last AI interaction, the project has achieved the following:

* **Core Infrastructure:** A foundational client structure is in place, including the main `Client` class, HTTP client builder, abstract API class, and basic exception handling.
* **Authentication:** The client can authenticate against an ArgoCD instance by exchanging username/password for a bearer token (via `SessionService`) or by using a pre-existing token.
* **Initial API Services:**
* `SessionService`: Implemented for login, logout, and user info.
* `AccountService`: Implemented for managing accounts and tokens.
* **Data Models:** PHP model classes corresponding to the implemented services' request/response structures have been created.
* **Project Configuration:** `composer.json` has been set up, and the project directory has been structured. The ArgoCD OpenAPI specification has been added to `reference/argocd_swagger.json`.

Further development will involve implementing the remaining ArgoCD API services (like the extensive `ApplicationService`), adding comprehensive unit tests, and refining documentation.

## Acknowledgements

* The initial structure and patterns were derived from the excellent [KnpLabs/php-github-api](https://github.com/KnpLabs/php-github-api) library.
* The target API is [ArgoCD](https://argo-cd.readthedocs.io/en/stable/), and its OpenAPI specification was used as the blueprint for API implementation.
180 changes: 88 additions & 92 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,134 +1,130 @@
# PHP GitHub API
# PHP ArgoCD API Client

![Build Status](https://github.com/KnpLabs/php-github-api/actions/workflows/ci.yml/badge.svg)
[![StyleCI](https://styleci.io/repos/3948501/shield?style=flat)](https://styleci.io/repos/3948501)
[![Latest Stable Version](https://poser.pugx.org/knplabs/github-api/v/stable)](https://packagist.org/packages/knplabs/github-api)
[![Total Downloads](https://poser.pugx.org/knplabs/github-api/downloads)](https://packagist.org/packages/knplabs/github-api)
[![Monthly Downloads](https://poser.pugx.org/knplabs/github-api/d/monthly)](https://packagist.org/packages/knplabs/github-api)
[![Daily Downloads](https://poser.pugx.org/knplabs/github-api/d/daily)](https://packagist.org/packages/knplabs/github-api)
[![Build Status](https://github.com/your-vendor/argocd-php-client/actions/workflows/ci.yml/badge.svg)](https://github.com/your-vendor/argocd-php-client/actions/workflows/ci.yml) <!-- Placeholder CI Badge -->
[![Latest Stable Version](https://poser.pugx.org/your-vendor/argocd-php-client/v/stable)](https://packagist.org/packages/your-vendor/argocd-php-client) <!-- Placeholder Packagist Badge -->
[![Total Downloads](https://poser.pugx.org/your-vendor/argocd-php-client/downloads)](https://packagist.org/packages/your-vendor/argocd-php-client) <!-- Placeholder Packagist Badge -->

A simple Object Oriented wrapper for GitHub API, written with PHP.
A PHP client for interacting with the ArgoCD API. This library provides an object-oriented interface to the ArgoCD REST API.

Uses [GitHub API v3](http://developer.github.com/v3/) & supports [GitHub API v4](http://developer.github.com/v4). The object API (v3) is very similar to the RESTful API.
This client's structure is based on the [KnpLabs/php-github-api](https://github.com/KnpLabs/php-github-api) library.

For more context on the AI-assisted development process of this library, please see [AI.md](AI.md).

## Features

* Light and fast thanks to lazy loading of API classes
* Extensively tested and documented
* Light and fast thanks to lazy loading of API classes.
* Object-oriented interface to the ArgoCD API.

## Requirements

* PHP >= 7.2
* A [PSR-17 implementation](https://packagist.org/providers/psr/http-factory-implementation)
* A [PSR-18 implementation](https://packagist.org/providers/psr/http-client-implementation)
* PHP ^8.3
* A [PSR-17 implementation](https://packagist.org/providers/psr/http-factory-implementation) (e.g., `nyholm/psr7`)
* A [PSR-18 implementation](https://packagist.org/providers/psr/http-client-implementation) (e.g., `symfony/http-client` or `guzzlehttp/guzzle`)

## Quick install

Via [Composer](https://getcomposer.org).

This command will get you up and running quickly with a Guzzle HTTP client.

```bash
composer require knplabs/github-api:^3.0 guzzlehttp/guzzle:^7.0.1 http-interop/http-factory-guzzle:^1.0
composer require your-vendor/argocd-php-client
```

## Advanced install

We are decoupled from any HTTP messaging client with help by [HTTPlug](https://httplug.io).

### Using a different http client
You will also need to install implementations for PSR-17 (HTTP Factories) and PSR-18 (HTTP Client), for example:

```bash
composer require knplabs/github-api:^3.0 symfony/http-client nyholm/psr7
```

To set up the Github client with this HTTP client

```php
use Github\Client;
use Symfony\Component\HttpClient\HttplugClient;

$client = Client::createWithHttpClient(new HttplugClient());
composer require symfony/http-client nyholm/psr7
```

Read more about [using different clients in our docs](doc/customize.md).

## Framework integrations

### Laravel

To integrate this library in laravel [Graham Campbell](https://github.com/GrahamCampbell) created [graham-campbell/github](https://github.com/GrahamCampbell/Laravel-GitHub). See the [installation instructions](https://github.com/GrahamCampbell/Laravel-GitHub#installation) to get started in laravel.

## Basic usage of `php-github-api` client

```php
<?php

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

$client = new \Github\Client();
$repositories = $client->api('user')->repositories('ornicar');
Or for Guzzle:
```bash
composer require guzzlehttp/guzzle php-http/guzzle7-adapter
```

From `$client` object, you have access to all available GitHub api endpoints.

## Cache usage

This example uses the PSR6 cache pool [redis-adapter](https://github.com/php-cache/redis-adapter). See http://www.php-cache.com/ for alternatives.
## Basic Usage

```php
<?php

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

use Cache\Adapter\Redis\RedisCachePool;

$client = new \Redis();
$client->connect('127.0.0.1', 6379);
// Create a PSR6 cache pool
$pool = new RedisCachePool($client);

$client = new \Github\Client();
$client->addCache($pool);

// Do some request

// Stop using cache
$client->removeCache();
// 1. Instantiate the client with your ArgoCD server URL
// Ensure your ArgoCD server URL is correct and accessible.
// The client will automatically append /api/v1 if it's not present.
$client = new ArgoCD\Client('https://your-argocd-server.example.com');

// 2. Authenticate
// Option A: Using username and password (fetches a token via SessionService)
try {
$client->authenticate('your-username', 'your-password');
echo "Successfully authenticated using username/password. Token: " . substr($client->getToken() ?? 'N/A', 0, 10) . "...\n";
} catch (ArgoCD\Exception\RuntimeException $e) {
die('Authentication failed: ' . $e->getMessage() . "\n");
}

// Option B: Using a pre-existing token
// try {
// $client->authenticate('your-argocd-api-token');
// echo "Successfully authenticated using pre-existing token.\n";
// } catch (ArgoCD\Exception\InvalidArgumentException $e) {
// die('Authentication failed with token: ' . $e->getMessage() . "\n");
// }


// 3. Access API services
try {
// Example: Get user info
$userInfo = $client->sessionService()->getUserInfo();
echo "Logged in as: " . $userInfo->getUsername() . "\n";
echo "Logged in status: " . ($userInfo->isLoggedIn() ? 'true' : 'false') . "\n";

// Example: List accounts (requires admin privileges typically)
// Note: Ensure the authenticated user has permissions for these operations.
// try {
// $accountsList = $client->accountService()->listAccounts();
// echo "Listing accounts:\n";
// if (count($accountsList->getItems()) > 0) {
// foreach ($accountsList->getItems() as $account) {
// echo " - Account Name: " . $account->getName() . ", Enabled: " . ($account->isEnabled() ? 'Yes' : 'No') . "\n";
// }
// } else {
// echo "No accounts found or not enough permissions.\n";
// }
// } catch (ArgoCD\Exception\RuntimeException $e) {
// echo "Could not list accounts: " . $e->getMessage() . "\n";
// }


} catch (ArgoCD\Exception\RuntimeException $e) {
die('API Error: ' . $e->getMessage() . "\n");
}

// Example: Delete the session (logout)
// try {
// $client->sessionService()->delete();
// echo "Successfully logged out.\n";
// } catch (ArgoCD\Exception\RuntimeException $e) {
// die('Logout failed: ' . $e->getMessage() . "\n");
// }

?>
```

Using cache, the client will get cached responses if resources haven't changed since last time,
**without** reaching the `X-Rate-Limit` [imposed by github](http://developer.github.com/v3/#rate-limiting).


## Documentation

See the [`doc` directory](doc/) for more detailed documentation.
Further documentation will be available as the library matures. For now, refer to the source code and the official [ArgoCD API documentation](https://cd.apps.argoproj.io/swagger-ui) (or the `reference/argocd_swagger.json` file in this repository).

## License

`php-github-api` is licensed under the MIT License - see the LICENSE file for details
This library is licensed under the MIT License - see the LICENSE file for details.

## Maintainers

Please read [this post](https://knplabs.com/en/blog/news-for-our-foss-projects-maintenance) first.

This library is maintained by the following people (alphabetically sorted) :
- [@acrobat](https://github.com/acrobat)
- [@Nyholm](https://github.com/Nyholm)
This library is currently maintained by:
- [Your Name](https://github.com/your-vendor) (or your GitHub username)

## Contributors

- Thanks to [Thibault Duplessis aka. ornicar](https://github.com/ornicar) for his first version of this library.
- Thanks to [Joseph Bielawski aka. stloyd](https://github.com/stloyd) for his contributions and support.
- Thanks to [noloh](https://github.com/noloh) for his contribution on the Object API.
- Thanks to [bshaffer](https://github.com/bshaffer) for his contribution on the Repo API.
- Thanks to [Rolf van de Krol](https://github.com/rolfvandekrol) for his countless contributions.
- Thanks to [Nicolas Pastorino](https://github.com/jeanvoye) for his contribution on the Pull Request API.
- Thanks to [Edoardo Rivello](https://github.com/erivello) for his contribution on the Gists API.
- Thanks to [Miguel Piedrafita](https://github.com/m1guelpf) for his contribution to the v4 & Apps API.
- Thanks to [Emre DEGER](https://github.com/lexor) for his contribution to the Actions API.

Thanks to GitHub for the high quality API and documentation.
* This project was significantly bootstrapped with the assistance of an AI agent. See [AI.md](AI.md) for more details.
* Structure and patterns inspired by [KnpLabs/php-github-api](https://github.com/KnpLabs/php-github-api).
* Thanks to the ArgoCD team for their excellent API and documentation.
```
56 changes: 12 additions & 44 deletions composer.json
Original file line number Diff line number Diff line change
@@ -1,65 +1,33 @@
{
"name": "knplabs/github-api",
"name": "your-vendor/argocd-php-client",
"description": "A PHP client for the ArgoCD API",
"type": "library",
"description": "GitHub API v3 client",
"homepage": "https://github.com/KnpLabs/php-github-api",
"keywords": ["github", "gh", "api", "gist"],
"license": "MIT",
"authors": [
{
"name": "KnpLabs Team",
"homepage": "http://knplabs.com"
},
{
"name": "Thibault Duplessis",
"email": "[email protected]",
"homepage": "http://ornicar.github.com"
"name": "Your Name",
"email": "[email protected]"
}
],
"require": {
"php": "^7.2.5 || ^8.0",
"ext-json": "*",
"php-http/cache-plugin": "^1.7.1|^2.0",
"php": "^8.3",
"php-http/client-common": "^2.3",
"php-http/discovery": "^1.12",
"php-http/httplug": "^2.2",
"php-http/multipart-stream-builder": "^1.1.2",
"psr/cache": "^1.0|^2.0|^3.0",
"psr/http-client-implementation": "^1.0",
"psr/http-factory-implementation": "^1.0",
"psr/http-message": "^1.0|^2.0",
"symfony/polyfill-php80": "^1.17",
"symfony/deprecation-contracts": "^2.2|^3.0"
"psr/http-message": "^1.0 || ^2.0"
},
"require-dev": {
"symfony/cache": "^5.1.8",
"guzzlehttp/psr7": "^2.7",
"http-interop/http-factory-guzzle": "^1.0",
"guzzlehttp/guzzle": "^7.2",
"php-http/mock-client": "^1.4.1",
"phpstan/phpstan": "^0.12.57",
"phpstan/extension-installer": "^1.0.5",
"phpstan/phpstan-deprecation-rules": "^0.12.5",
"phpunit/phpunit": "^8.5 || ^9.4",
"symfony/phpunit-bridge": "^5.2"
"phpunit/phpunit": "^9.5"
},
"autoload": {
"psr-4": { "Github\\": "lib/Github/" }
},
"autoload-dev": {
"psr-4": { "Github\\Tests\\": "test/Github/Tests/"}
},
"extra": {
"branch-alias": {
"dev-2.x": "2.20.x-dev",
"dev-master": "3.16-dev"
"psr-4": {
"ArgoCD\\": "src/ArgoCD/"
}
},
"config": {
"allow-plugins": {
"phpstan/extension-installer": true,
"composer/package-versions-deprecated": true,
"php-http/discovery": true
"autoload-dev": {
"psr-4": {
"ArgoCD\\Tests\\": "tests/"
}
}
}
Loading
Loading