Download the PHP package labelzoom/sdk without Composer

LabelZoom PHP SDK

Official PHP client for the LabelZoom API. Converts barcode labels between ZPL, EPL, TSPL, DPL, PDF, LabelZoom XML/JSON, and raster images.

PHP 8.1+. PSR-18 / PSR-17 throughout, so it drops into Guzzle, Symfony HttpClient, or the bundled cURL client with no adapter.

Install

Pre-1.0. The public API is stable in practice and covered by a shared conformance suite, but it stays on 0.x until all seven language SDKs have validated the same contract — two contract-level corrections have already come out of that process.

Quick start

An API key is optional. Without one you get the free tier — watermarked output, first label only, a 1 MB request cap, and no multi-page, JSON-target, or image-to-image conversion.

With a key:

Omitting the argument entirely reads LABELZOOM_API_KEY from the environment. Passing null or '' explicitly forces anonymous mode and suppresses that fallback — the two are deliberately different, so a config value that resolves to empty cannot silently pick up an unrelated key.

The client is stateless once constructed and safe to keep for the life of the process. Create one per application, not one per request.

Formats

Sources (12, plus url): zpl epl tspl dpl xml json pdf png bmp gif jpg jpeg

Targets (11): zpl epl tspl dpl xml json pdf png bmp gif jpeg

jpg and url are source-only — jpg normalizes to jpeg, and url is a fetch instruction rather than a format. SourceFormat and TargetFormat are separate enums, so there is no TargetFormat::Url to write:

A PHPStan error, not a runtime 404. The two typecheck/* conformance cases assert exactly this, and PHP is the only dynamically executed SDK that runs them rather than declaring them skipped.

epl, tspl and dpl are targets as well as sources — fromPdf($bytes)->toEpl() is a real conversion. Their output is text/plain with every label concatenated, but EPL's GW and TSPL's BITMAP commands inline raw binary: read $result->getBytes() rather than $result->getText() whenever a label might carry graphics.

Reading source bytes from wherever they live:

fromUrl() has the server fetch a URL you supply and convert what it finds. Validate the URL first if it came from untrusted input.

Options

Every with* call maps to one field of the API's ?params= object.

Only options you actually set are sent. The SDK never fills in a client-side default, so a change to a server default reaches you without an SDK upgrade.

withData() takes either a list of records or a single record, which is wrapped rather than rejected. Each record produces one label.

Results

getBytes() is authoritative — five of the eleven targets are binary, and the epl/tspl text targets can inline binary of their own.

Errors

Every non-2xx throws a typed exception carrying the server's own message, the raw body, and the X-LZ-Request-Id support handle. The body is never discarded, and getMessage() is truncated to 512 characters while getRawBody() is not.

BadRequestException, UnauthorizedException, ForbiddenException, NotFoundException, PayloadTooLargeException, RateLimitedException and ServerErrorException all extend LabelZoomException, which extends RuntimeException.

Two exceptions deliberately do not extend it, because neither has a status, a body or a request id to carry, and a handler written for server failures should not swallow them:

• ValidationException (extends InvalidArgumentException) — the calling code is wrong, and no HTTP request was made.
• TransportException (extends RuntimeException) — no response was ever produced. Thrown only once retries are exhausted.

Retries

429, 5xx and transport failures are retried automatically: 3 attempts, 1s/2s/4s with full jitter, honouring a longer Retry-After on any retryable status. Other 4xx responses throw immediately — a malformed request will not become valid on a second attempt.

Bring your own HTTP client

The bundled CurlHttpClient is a default, not a dependency. Any PSR-18 client works:

Pass PSR-17 factories too if you would rather not use the bundled nyholm/psr7:

Testing your own code

The transport and the retry delay are both injectable, so retry logic can be tested without spending the wall-clock time:

Development

The test suite runs the shared conformance fixtures that every LabelZoom SDK is checked against, and asserts it ran all of them — PHP declares no skips. See docs/CONFORMANCE.md.

License

MIT — see LICENSE.