README

The send side of Matte — self-hosted, unmetered image background removal on Laravel Cloud. Install it in any Laravel app to call your self-hosted Matte server with one line: Matte::remove($image).

Use the default integration guide when an agent is installing or migrating to this client.

Read-only mirror. This repository is a read-only split of the artisan-build/matte monorepo. Issues and pull requests are disabled here — please open them on the monorepo.

What it does

matte-client is a thin convenience SDK over the Matte HTTP API. It is a fast-path, not a requirement — the server is a plain HTTP API, so anything can POST to it directly. The SDK just makes the common Laravel case ergonomic.

Matte::remove($image, $options) → a JobHandle (async submit). The $image can be a file path, raw bytes, an UploadedFile, or an SplFileInfo.
Matte::removeSync($image, $options) → the transparent PNG bytes, inline, for small / interactive cases.
JobHandle → status(), wait($timeout) (polls to done/failed/timeout), result() (fetches the PNG).
Registered callbacks → pass a server-registered destination identifier as the third remove() argument. The historical parameter name remains $callbackUrl for source compatibility, but values are identifiers, never URLs.

It speaks the matte-contracts wire protocol and authenticates with a Bearer token.

Async polling

The default keeps the install zero-infrastructure: no public endpoint, no websockets.

Poll → event (default). Submit, then AwaitRemovalJob::dispatch($handle->id()). The job polls the server on your app's own queue, optionally stores the result to MATTE_STORE_DISK, and fires a MatteRemovalCompleted event you listen for. Works everywhere — localhost, CI, behind a firewall.

use ArtisanBuild\MatteClient\Facades\Matte;
use ArtisanBuild\MatteClient\Jobs\AwaitRemovalJob;

$handle = Matte::remove($request->file('photo'), ['mode' => 'grabcut', 'preset' => 'quality']);
AwaitRemovalJob::dispatch($handle->id());        // → MatteRemovalCompleted

// or, inline:
$png = Matte::removeSync($smallImage);

Activation — by presence of config

The client is active when MATTE_URL and MATTE_TOKEN are set. Async completion uses polling.

Installation

composer require artisan-build/matte-client
php artisan matte:install

matte:install prompts for the Matte server URL and bearer credential, writes MATTE_URL and MATTE_TOKEN to your .env, publishes the config, and pins matte-contracts to a caret constraint. On the Matte server, mint the credential with:

php artisan bfc:credential:mint installation '<consumer-installation-ref>' --kind=bearer --purpose=consumption --name='matte-<app-id>' --local

The client mounts POST /matte/callback by default. Configure its exact installation-bound callback scope, register the matching destination on the Matte server, and install the delivered verification credential with InstallCallbackCredential. That action requires a trusted Built for Cloud HmacCredentialIssuerClient and delegates storage to InstallHmacCredentialFromClaim; no callback secret belongs in Matte config. The receiver dispatches MatteRemovalCompleted only after Built for Cloud verifies the bound signature and Matte validates the completion envelope.

License

MIT. See LICENSE.

artisan-build / matte-client

Package info

Security

Statistics