Caretly PHP client

Client for the Caretly API: render ZPL labels to PDF or PNG.

• PHP 8.1 or later.
• Bring your own HTTP client: any PSR-18 client works (Guzzle, Symfony HttpClient, …) and is found automatically.
• Retries rate limits and overload automatically, without ever billing a label twice.

Install

composer require caretly/caretly

If your project has no PSR-18 client yet, add one, for example:

composer require guzzlehttp/guzzle
# or
composer require symfony/http-client nyholm/psr7

Quickstart

use Caretly\Client;

$caretly = new Client(apiKey: 'zpl_test_…'); // or set CARETLY_API_KEY

$result = $caretly->render("^XA^FO50,50^A0N,50,50^FDHello^FS^XZ");
$result->saveTo('label.pdf');

echo $result->pageCount;    // 1
echo $result->labelsBilled; // 0 for a test key

Get an API key in the console. Keys starting with zpl_test_ are free and watermark every label with TEST; zpl_live_ keys are billed per label.

PNG

use Caretly\Format;
use Caretly\RenderOptions;

$png = $caretly->render($zpl, new RenderOptions(format: Format::Png, page: 2, dpmm: 12));
$png->saveTo('page-2.png');

// or the shorthand
$png = $caretly->renderPng($zpl, page: 2);

Several files

Each file starts from a fresh printer state; pages follow the order of the array.

$result = $caretly->renderFiles([
    'shipping.zpl' => file_get_contents('shipping.zpl'),
    'returns.zpl'  => file_get_contents('returns.zpl'),
]);

$result->filePageCounts; // [2, 1]

Client options

$caretly = new Client(
    apiKey: null,                     // falls back to getenv('CARETLY_API_KEY'); optional for self-hosted servers
    baseUrl: 'https://caretly.dev',
    maxRetries: 2,                    // retries for 429, 503 and connection errors (not timeouts)
    timeout: 30.0,                    // seconds; see below
    httpClient: null,                 // any Psr\Http\Client\ClientInterface
    requestFactory: null,             // Psr\Http\Message\RequestFactoryInterface
    streamFactory: null,              // Psr\Http\Message\StreamFactoryInterface
    sleep: null,                      // Closure(float $seconds): void, used between retries
);

PSR-18 has no standard way to set a timeout. When you do not inject httpClient, the client creates a Guzzle or Symfony client itself (whichever is installed) with timeout applied, and otherwise falls back to php-http/discovery. When you inject your own client, configure its timeout there.

Render options

Option	Values	Default (server)	Meaning
format	Format::Pdf, Format::Png	PDF	A PDF holds every page; a PNG is one page.
page	int ≥ 1	1	The page shown in a PNG.
dpmm	6, 8, 12, 24	8	Printer resolution in dots per millimetre.
timings	bool	false	Return a Server-Timing header ($result->serverTiming).
idempotencyKey	string, 1–255 chars	generated	A retry with the same key and content is billed once.
compress	bool	false	Gzip the request body (needs ext-zlib).

Invalid page, dpmm or idempotencyKey values throw \InvalidArgumentException before any request.

Result

RenderResult is read-only:

Property	Type	Meaning
content	string	The PDF or PNG bytes.
contentType	string	application/pdf or image/png.
pageCount	int	Total pages across the input.
filePageCounts	list<int>	Pages per file for renderFiles(), else empty.
labelsBilled	?int	Labels billed (0 for test keys); null without keys.
rateLimit	?RateLimit	limit and remaining of the burst; null when absent.
serverTiming	?string	Raw Server-Timing header, with timings.

saveTo(string $path) writes the bytes to a file.

$caretly->health() returns true when the server answers GET /health with ok, and false otherwise (it never throws).

Errors

Every runtime exception extends Caretly\Exception\CaretlyException.

以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗