Download the PHP package kinetistack-io/php-sdk without Composer

KinetiStack PHP SDK

Framework-Agnostic PHP Client Library for KinetiStack API.

Installation

Usage

Initialization

HTTP Client Flexibility (PSR-18 & Symfony)

The SDK is strictly framework-agnostic. It does not force a concrete HTTP client implementation:

• Auto-Discovery: If httpClient is omitted or null, php-http/discovery automatically discovers any installed PSR-18 client (such as Guzzle) or Symfony's HTTP Client.
• PSR-18 (Guzzle, etc.): Inject any Psr\Http\Client\ClientInterface instance directly (e.g. new KinetiClient($host, $key, $guzzleClient)).
• Symfony HTTP Client: Existing Symfony projects can inject Symfony\Contracts\HttpClient\HttpClientInterface for full backward compatibility.

Transient Error Retries & Backoff

When max_retries is configured in $options, the SDK automatically retries transient HTTP errors:

• HTTP 429 (Too Many Requests): Automatically delays subsequent retries by respecting the server's Retry-After response header (or falls back to exponential backoff).
• HTTP 503 (Service Unavailable): Automatically retries using exponential backoff.
• Non-transient errors (such as HTTP 400, 401, 403, 404, 422, or 500) fail immediately without retrying.

If all retry attempts are exhausted, the corresponding typed exception (e.g., RateLimitException or ServiceUnavailableException) is thrown.

Synchronous Image Analysis

Batch Processing

Exponential Backoff & Polling Constants

waitForBatchJob() implements an adaptive polling strategy with jitter:

• Exponential progression: Polling begins at $pollIntervalSeconds (default: 2s) and doubles on each subsequent check (e.g., 2s -> 4s -> 8s -> 10s).
• Interval cap: The sleep interval between checks never exceeds $maxPollIntervalSeconds (default: 10s).
• Randomized jitter: A randomized jitter between 0 and 500ms is added to every sleep duration to prevent synchronized polling spikes across distributed workers.
• Progress monitoring: The optional $onProgress callback receives the updated BatchJobDto on each poll check.

Default constants exposed on KinetiClient:

• KinetiClient::DEFAULT_POLL_INTERVAL_SECONDS = 2
• KinetiClient::DEFAULT_MAX_POLL_INTERVAL_SECONDS = 10
• KinetiClient::DEFAULT_TIMEOUT_SECONDS = 60

Webhook Verification

Verify incoming HMAC-SHA256 signatures for webhook events (e.g. from the X-Kineti-Signature header):

Error Handling

The SDK maps HTTP error responses to typed exceptions (RFC 9457 compliant):

Note on Transient Errors: When max_retries is specified in client options (e.g., ['max_retries' => 3]), transient HTTP errors (429 Too Many Requests respecting Retry-After header, and 503 Service Unavailable) are automatically retried with exponential backoff before throwing RateLimitException or ServiceUnavailableException.

Admin API (AdminClient)

The SDK provides AdminClient as a dedicated sibling client for administrative operations under /api/v1/admin/*, authenticated via LexikJWT Bearer tokens (Authorization: Bearer <jwt>).

Initialization & Authentication

Organizations & Projects

API Key Management

Usage & Analytics

Development

No local PHP or Composer installation is required. Everything runs in one-off Docker containers via docker compose and make.

Prerequisites

• Docker & Docker Compose
• make

Common Commands

CI/CD & Release Workflow

The SDK uses automated CI/CD workflows for testing, static analysis, and releases:

• CI Pipeline (.github/workflows/ci.yml): Runs on pushes and pull requests targeting main. Executes test matrices across PHP 8.1, 8.2, 8.3, and 8.4, followed by PHP CS Fixer and PHPStan static analysis.
• Release Pipeline (.github/workflows/release.yml): Triggered automatically when a version tag matching v*.*.* (e.g., v1.0.0) is pushed to the repository.
  1. Validation (validate): Checks platform requirements via composer check-platform-reqs and runs PHPUnit across PHP 8.1, 8.2, 8.3, and 8.4.
  2. Quality Checks (quality-checks): Ensures code conforms to PSR-12 and passes PHPStan Level 8 static analysis.
  3. Release (release): Requires both validate and quality-checks to pass. Publishes a GitHub Release (with auto-generated release notes and automatic pre-release detection) and triggers a synchronization webhook to the Packagist API via authenticated cURL.

Required Repository Secrets

The release workflow requires the following repository secrets to be configured in GitHub:

The workflow also requires GitHub Actions default GITHUB_TOKEN with contents: write permissions (configured automatically in release.yml) to publish releases. Fork runs automatically skip the release job if secrets are not configured.

Contributing

Contributions are welcome! Please refer to CONTRIBUTING.md for detailed local development, testing, and release guidelines.

Before opening a pull request, ensure that:

1. Code adheres to PSR-12 standards (make cs-check / make cs-fix).
2. Static analysis passes at PHPStan Level 8 (make phpstan).
3. Unit tests pass across all supported PHP versions (make test-all).
4. All checks pass locally via make check before opening a pull request.

Security

If you discover a security vulnerability within this SDK, please send an email to [email protected] or use GitHub Private Vulnerability Reporting. All security vulnerabilities will be promptly addressed.

License

The KinetiStack PHP SDK is open-sourced software licensed under the MIT license.