Skip to main content

PHP

The giveitsmaller/sdk package is the official PHP client for GISL (Give It Smaller) — compress, convert, thumbnail, merge, and archive images, video, audio, and documents from PHP 8.1+.

Install​

The SDK targets the PSR-18 (HTTP client) and PSR-17 (HTTP factories) standards and resolves a concrete implementation through php-http/discovery. Install it alongside any PSR-18 client — Guzzle is the common choice:

composer require giveitsmaller/sdk guzzlehttp/guzzle http-interop/http-factory-guzzle

Requires PHP ^8.1. If you already have a PSR-18 client (e.g. Symfony HttpClient), inject it directly instead of installing Guzzle.

Published on Packagist

The composer require above is all you need — giveitsmaller/sdk and its transitive giveitsmaller/contracts dependency are on Packagist, with no repositories block or auth token required.

Authenticate​

Every request is authenticated with an API key sent as a Bearer token. Get a key from the dashboard at giveitsmaller.com. The SDK resolves the key from the first source that provides one: the explicit apiKey: argument, then GISL_API_KEY, then the [default] profile in ~/.gisl/credentials.

use Gisl\Sdk\Gisl;

// Explicit key:
$client = Gisl::create(apiKey: 'sk_live_...');

// Or rely on GISL_API_KEY / ~/.gisl/credentials:
$client = Gisl::create();

With no key found, Gisl::create() throws GislMissingCredentialsError before any network call. Target a non-production environment with Gisl::create(apiKey: 'sk_...', environment: Environment::Staging).

Quickstart​

The SDK is file-first: you start from a file (->file($path) for one, ->files([$paths]) for many) and call operations on it — upload, workflow creation, and waiting are handled for you in one chain.

<?php
require 'vendor/autoload.php';

use Gisl\Sdk\Gisl;
use Gisl\Sdk\Generated\SdkSpec\Enums\OptimizeFor;

$client = Gisl::create(apiKey: 'sk_...');

// Upload → compress → wait → resolve the download URL, in one chain.
$run = $client->file('./photo.jpg')
    ->compress(OptimizeFor::Balanced)
    ->run(maxWait: '5m');

echo $run->url; // pre-signed download URL

That is the full round trip. Worth knowing:

  • Presets express intent. OptimizeFor::Size, ::Balanced, and ::Quality pick sensible options for the input's media type. See Compress for per-call options.
  • run() waits up to 10 minutes by default — override with maxWait. For live progress instead of polling, subscribe to progress events.
  • Failures throw typed errors — see Errors.
Low-level escape hatch

File-first is the recommended path. When you need full control over the workflow payload, the low-level surface (uploadFile → createWorkflow → waitForWorkflow → getWorkflowDownloads) is available, with source factories from Gisl\Sdk\Sources.

Where next​

  • Installation — every language, side by side.
  • Quickstart — the end-to-end walkthrough.
  • Operations — compress, convert, thumbnail, merge, archive.
  • Workflows — how jobs, sources, and outputs fit together.
  • Errors — the error taxonomy and retry guidance.