Download the PHP package juststeveking/tabstack without Composer

Tabstack PHP API Library

This library provides convenient access to the Tabstack REST API from PHP.

Installation

Usage

Request & Response types

All request parameters are typed value objects and all responses are strongly-typed DTOs. You may import and use them directly:

Effort levels

The extract and generate endpoints accept an optional EffortLevel enum that controls the speed vs. capability tradeoff:

Geotargeting

Any request that accepts a GeoTarget will route the fetch through a proxy in the specified country (ISO 3166-1 alpha-2):

Agent endpoints (streaming)

agent()->automate() and agent()->research() always stream via Server-Sent Events. Instead of a raw PSR-7 response, they return a typed, iterable stream (AutomateStream / ResearchStream) that parses the SSE body incrementally and yields typed events as they arrive.

Three ways to consume a stream:

Typed results

result() consumes the stream and returns a typed view of the final complete event:

Resuming a stream

Each event exposes its SSE id and the stream tracks the latest via lastEventId(). If a connection drops, resume by passing it back — the SDK sends it as the Last-Event-ID header:

Event payloads

Each event exposes a string event name and a data payload. Object payloads are wrapped in an immutable Payload that supports both accessor and array syntax; scalar payloads are returned as-is.

There is no typed class per event type — the event set is open-ended, so payloads stay flexible.

Interactive mode

When an automate task is started with interactive: true, the stream emits interactive:form_data:request events carrying a requestId. Respond with agent()->automateInput() — supply field values or cancel. Input requests expire after two minutes.

Action firewall

automate runs behind an action firewall that guards against prompt injection. Two AgentAutomate parameters relax it — use with care:

⚠️ unsafeMode removes injection protection for every host. Only set trustedHostnames for hosts you fully control.

Configuration

Tabstack::make() works with just an API key, but accepts an optional base URI (to target a different environment) and your own PSR-18 client (to configure timeouts, retries, logging, or any middleware):

Every request is sent with a User-Agent: tabstack-php/{version} header.

Retries

By default the client retries rate-limited (429) and connection failures up to twice, honouring the Retry-After header and falling back to exponential backoff. Tune it with RetryConfig — including opt-in retries for 5xx server errors:

Error handling

Any non-2xx response throws a TabstackException subclass, mapped from the HTTP status. Transport failures (DNS, connection refused, timeouts) are wrapped in a ConnectionException. Every exception exposes the statusCode and the decoded response body.

All extend TabstackException, so catch that to handle everything. Streaming endpoints (automate, research) throw the same exceptions if the request fails before the stream begins.

Requirements

• PHP 8.5 or later
• A PSR-18 HTTP client (e.g. symfony/http-client) — discovered automatically via php-http/discovery
• A PSR-17 HTTP factory (e.g. nyholm/psr7) — included as a dependency

Semantic versioning

This package generally follows SemVer conventions, though certain backwards-incompatible changes may be released as minor versions:

1. Changes that only affect static types, without breaking runtime behaviour.
2. Changes to library internals which are technically public but not intended or documented for external use.
3. Changes that we do not expect to impact the vast majority of users in practice.

We are keen for your feedback; please open an issue with questions, bugs, or suggestions.

Credits

• Steve McDougall
• All Contributors

LICENSE

The MIT License (MIT). Please see License File for more information.