PHPackages                             brd6/tinybird-sdk-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. brd6/tinybird-sdk-php

ActiveLibrary[API Development](/categories/api)

brd6/tinybird-sdk-php
=====================

Tinybird SDK for PHP

0.1.2(5mo ago)391[2 PRs](https://github.com/brd6/tinybird-sdk-php/pulls)MITPHPPHP ^8.1CI passing

Since Dec 11Pushed 5mo agoCompare

[ Source](https://github.com/brd6/tinybird-sdk-php)[ Packagist](https://packagist.org/packages/brd6/tinybird-sdk-php)[ RSS](/packages/brd6-tinybird-sdk-php/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (22)Versions (6)Used By (0)

 **Tinybird SDK for PHP**

 [![Source Code](https://camo.githubusercontent.com/6de2847f05a9126d43354b7a775709507de1f64ebb27de48ad51de5358620859/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f736f757263652d627264362f74696e79626972642d2d73646b2d2d7068702d626c75652e7376673f7374796c653d666c61742d737175617265)](https://github.com/brd6/tinybird-sdk-php) [![Download Package](https://camo.githubusercontent.com/9459e1863a39395a1f134ff36efbaee7ef63f48386af83097c660cacfea5cce0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f627264362f74696e79626972642d73646b2d7068702e7376673f7374796c653d666c61742d737175617265266c6162656c3d72656c65617365)](https://packagist.org/packages/brd6/tinybird-sdk-php) [![PHP Programming Language](https://camo.githubusercontent.com/51cd278b1ecfe8c7888fa6cf66aeba6fdad0608cd3b932976654ca563d398e6a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f627264362f74696e79626972642d73646b2d7068702e7376673f7374796c653d666c61742d73717561726526636f6c6f72423d253233383839324246)](https://php.net) [![Read License](https://camo.githubusercontent.com/752373526c78bcea74a8df955ed089af0c84556f79ea03ea94e535b7a7387626/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f627264362f74696e79626972642d73646b2d7068702e7376673f7374796c653d666c61742d73717561726526636f6c6f72423d6461726b6379616e)](https://github.com/brd6/tinybird-sdk-php/blob/main/LICENSE) [![Build Status](https://camo.githubusercontent.com/958f0ac4ed8b3be7b76c09604016236058c00e0c7feb9ecbb1ec6a410a8e929f/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f627264362f74696e79626972642d73646b2d7068702f2e6769746875622f776f726b666c6f77732f636f6e74696e756f75732d696e746567726174696f6e2e796d6c3f6272616e63683d6d61696e267374796c653d666c61742d737175617265266c6f676f3d676974687562)](https://github.com/brd6/tinybird-sdk-php/actions/workflows/continuous-integration.yml)

PHP SDK for the [Tinybird API](https://www.tinybird.co) — the real-time data platform for developers. Build low-latency, high-concurrency analytics APIs over any data source in minutes. Ingest millions of events per second, query with SQL, and publish endpoints instantly.

Synopsis
--------

[](#synopsis)

```
// Ingest → Query → Results
$tinybird = Client::create('p.your_token');
$tinybird->events()->send('clicks', ['user' => 'alice', 'page' => '/home']);
$result = $tinybird->query()->sql('SELECT count() FROM clicks');
// → {"data":[{"count()":1}],"rows":1}
```

Features
--------

[](#features)

- **High-frequency ingestion** — Send millions of events per second via Events API
- **Schema generation** — Analyze files to generate Data Source schemas
- **Sub-second queries** — Execute SQL queries with instant results
- **Concurrent requests** — Batch multiple queries for parallel execution
- **Multi-region support** — EU, US, AWS, GCP, and custom deployments
- **Built-in retry logic** — Automatic retry with exponential backoff
- **PSR-18 compatible** — Works with Symfony, Guzzle, or any HTTP client
- **Type-safe resources** — Full PHP 8.1+ support with strict types

Installation
------------

[](#installation)

Install this package using [Composer](https://getcomposer.org):

```
composer require brd6/tinybird-sdk-php
```

This package uses [PSR-18](https://www.php-fig.org/psr/psr-18/) HTTP client abstraction. You can use any compatible HTTP client. For quick setup with Symfony HTTP client:

```
composer require brd6/tinybird-sdk-php symfony/http-client nyholm/psr7
```

Quick Start
-----------

[](#quick-start)

```
use Brd6\TinybirdSdk\Client;

// Create client (uses EU region by default)
$tinybird = Client::create('p.your_token_here');

// Ingest events
$tinybird->events()->send('events', [
    ['timestamp' => '2025-01-01 00:00:00', 'event' => 'page_view', 'user_id' => 'user_123'],
    ['timestamp' => '2025-01-01 00:00:01', 'event' => 'click', 'user_id' => 'user_456'],
]);

// Query with SQL
$result = $tinybird->query()->sql('SELECT count() FROM events');

// Call a Pipe endpoint
$result = $tinybird->pipes()->query('analytics_endpoint', ['date_from' => '2025-01-01']);
```

### Region Selection

[](#region-selection)

```
use Brd6\TinybirdSdk\Client;
use Brd6\TinybirdSdk\Enum\Region;

// US East
$tinybird = Client::forRegion('p.your_token', Region::GCP_US_EAST4);

// AWS EU Central
$tinybird = Client::forRegion('p.your_token', Region::AWS_EU_CENTRAL_1);

// Tinybird Local
$tinybird = Client::local('your_local_token');

// Custom port
$tinybird = Client::local('your_local_token', 8080);
```

### Custom Endpoint

[](#custom-endpoint)

For private deployments or custom domains:

```
use Brd6\TinybirdSdk\Client;
use Brd6\TinybirdSdk\ClientOptions;

$options = (new ClientOptions())
    ->setToken('your_token')
    ->setBaseUrl('https://your-custom-endpoint.com');

$tinybird = new Client($options);
```

Usage
-----

[](#usage)

### Analyze API

[](#analyze-api)

Analyze files to generate Tinybird Data Source schemas. Useful before creating `.datasource` files.

```
// Analyze NDJSON records
$result = $tinybird->analyze()->analyzeRecords([
    ['timestamp' => '2025-01-01 00:00:00', 'event' => 'page_view', 'user_id' => 'user_123'],
    ['timestamp' => '2025-01-01 00:00:01', 'event' => 'click', 'user_id' => 'user_456'],
]);

// Get the generated schema (ready for .datasource files)
echo $result->getSchema();
// Output: timestamp DateTime `json:$.timestamp`, event String `json:$.event`, ...

// Inspect analyzed columns
foreach ($result->columns as $col) {
    echo "{$col->name}: {$col->recommendedType}";
    if ($col->presentPct < 1) {
        echo " (nullable)";
    }
}

// Analyze a remote file
$result = $tinybird->analyze()->analyzeUrl('https://example.com/data.ndjson');

// Analyze raw content
$result = $tinybird->analyze()->analyzeContent($csvContent);
```

### Events API

[](#events-api)

High-frequency data ingestion optimized for real-time analytics. This is the recommended way to ingest data in Tinybird Forward workspaces.

```
// Send single event
$result = $tinybird->events()->send('events', [
    'timestamp' => '2025-01-01 00:00:00',
    'event' => 'page_view',
    'user_id' => 'user_123',
]);

// Send batch events
$result = $tinybird->events()->send('events', [
    ['timestamp' => '2025-01-01 00:00:00', 'event' => 'page_view', 'user_id' => 'user_123'],
    ['timestamp' => '2025-01-01 00:00:01', 'event' => 'click', 'user_id' => 'user_456'],
]);

// Check result
echo $result->successfulRows;   // Rows ingested
echo $result->quarantinedRows;  // Rows failed validation

// Send raw NDJSON
$tinybird->events()->sendRaw('events', $ndjsonString);
```

### Data Sources

[](#data-sources)

Read Data Source information and metadata.

```
// List all Data Sources
$datasources = $tinybird->dataSources()->list();

foreach ($datasources as $ds) {
    echo $ds->name;
    echo $ds->getRowCount();
    echo $ds->getBytes();
}

// Get Data Source details
$info = $tinybird->dataSources()->retrieve('events');

echo $info->id;
echo $info->name;
echo $info->type;
echo $info->createdAt;

// Access columns
foreach ($info->columns as $column) {
    echo $column->name;
    echo $column->type;
}

// Get quarantine data
$quarantine = $tinybird->dataSources()->quarantine('events');
```

> **Note:** For schema changes, use the Tinybird CLI (`tb deploy`). See [Tinybird Forward documentation](https://www.tinybird.co/docs/forward).

### Query API

[](#query-api)

Execute raw SQL queries against your Data Sources.

```
// Simple query
$result = $tinybird->query()->sql('SELECT count() FROM events');

echo $result->rows;
echo $result->data[0]['count()'];

// Query with parameters
$result = $tinybird->query()->sql(
    'SELECT * FROM events WHERE user_id = {user_id:String} LIMIT {limit:Int32}',
    ['user_id' => 'user_123', 'limit' => 100]
);

// Access results
foreach ($result->data as $row) {
    echo $row['event'];
}

// Query statistics
echo $result->getElapsedTime();
echo $result->getRowsRead();
echo $result->getBytesRead();
```

#### Batch Queries

[](#batch-queries)

Execute multiple SQL queries concurrently for better performance:

```
// Run multiple queries in parallel
$results = $tinybird->query()->batchSql([
    'total_users' => 'SELECT count() FROM users',
    'active_today' => 'SELECT count() FROM events WHERE date = today()',
    'revenue' => 'SELECT sum(amount) FROM orders',
]);

// Access individual results
foreach ($results as $key => $result) {
    if ($result->isSuccess()) {
        echo "{$key}: " . $result->getData()->data[0];
    } else {
        echo "{$key} failed: " . $result->getException()->getMessage();
    }
}

// Or get data directly
$totalUsers = $results['total_users']->getData()->data[0]['count()'];
```

### Pipes API

[](#pipes-api)

Query published API Endpoints and list Pipes.

```
// List Pipes
$pipes = $tinybird->pipes()->list();

// Query a Pipe endpoint
$result = $tinybird->pipes()->query('my_analytics_endpoint', [
    'start_date' => '2025-01-01',
    'end_date' => '2025-12-31',
    'limit' => 1000,
]);

foreach ($result->data as $row) {
    // Process results
}
```

#### Batch Pipe Queries

[](#batch-pipe-queries)

Query multiple Pipe endpoints concurrently:

```
// Simple: key is pipe name
$results = $tinybird->pipes()->batchQuery([
    'user_stats' => ['date' => '2025-01-01'],
    'event_counts' => ['type' => 'click'],
]);

// Query same pipe multiple times using # alias
$results = $tinybird->pipes()->batchQuery([
    'user_stats#jan' => ['date' => '2025-01-01'],
    'user_stats#feb' => ['date' => '2025-02-01'],
    'user_stats#mar' => ['date' => '2025-03-01'],
]);

// Handle results with error isolation
foreach ($results as $key => $result) {
    if ($result->isSuccess()) {
        $data = $result->getData();
        echo "{$key}: {$data->rows} rows";
    } else {
        // Individual failures don't affect other queries
        echo "{$key} failed: " . $result->getException()->getMessage();
    }
}
```

### Jobs API

[](#jobs-api)

Monitor and manage background jobs (imports, populates, copies).

```
use Brd6\TinybirdSdk\RequestParameters\ListJobsParams;
use Brd6\TinybirdSdk\Enum\JobStatus;

// List recent jobs
$jobs = $tinybird->jobs()->list();

// Filter by status
$jobs = $tinybird->jobs()->list(new ListJobsParams(status: JobStatus::DONE));

// Get job details
$job = $tinybird->jobs()->retrieve($jobId);
echo $job->status; // waiting, working, done, error

// Cancel a running job
$tinybird->jobs()->cancel($jobId);
```

### Environment Variables API

[](#environment-variables-api)

Manage workspace variables for use in Pipes.

```
// List all variables
$vars = $tinybird->variables()->list();

// Create a variable
$var = $tinybird->variables()->create('API_KEY', 'secret_value');

// Update a variable
$tinybird->variables()->update('API_KEY', 'new_value');

// Delete a variable
$tinybird->variables()->remove('API_KEY');
```

### Tokens API

[](#tokens-api)

Manage workspace tokens for authentication.

```
use Brd6\TinybirdSdk\RequestParameters\CreateTokenParams;

// List all tokens
$tokens = $tinybird->tokens()->list();

// Create a token with scopes
$token = $tinybird->tokens()->create(new CreateTokenParams(
    name: 'my_token',
    scopes: ['PIPES:READ', 'DATASOURCES:READ'],
));

// Refresh (rotate) a token
$newToken = $tinybird->tokens()->refresh('my_token');

// Delete a token
$tinybird->tokens()->remove('my_token');
```

### Sink Pipes API

[](#sink-pipes-api)

Export data to object stores (S3, GCS).

```
use Brd6\TinybirdSdk\RequestParameters\CreateSinkParams;

// Create a sink pipe
$pipe = $tinybird->sinkPipes()->create($pipeId, $nodeId, new CreateSinkParams(
    connection: 's3://bucket/path',
    path: 'exports/',
));

// Trigger a sink export
$result = $tinybird->sinkPipes()->trigger($pipeId);

// Get S3 integration settings
$settings = $tinybird->sinkPipes()->getS3Settings();
```

### Error Handling

[](#error-handling)

```
use Brd6\TinybirdSdk\Exception\ApiException;
use Brd6\TinybirdSdk\Exception\AuthenticationException;
use Brd6\TinybirdSdk\Exception\RateLimitException;
use Brd6\TinybirdSdk\Exception\RequestTimeoutException;

try {
    $result = $tinybird->pipes()->query('my_endpoint');
} catch (AuthenticationException $e) {
    // Invalid or expired token (401/403)
    // Includes helpful suggestions for region mismatches
} catch (RateLimitException $e) {
    // Too many requests (429)
    $retryAfter = $e->getRetryAfter();
    $limit = $e->getRateLimitLimit();
    $remaining = $e->getRateLimitRemaining();
} catch (RequestTimeoutException $e) {
    // Request timed out
} catch (ApiException $e) {
    // Other API errors
    $code = $e->getCode();
    $message = $e->getMessage();
    $response = $e->getResponse();
}
```

Regions
-------

[](#regions)

RegionEnumAPI Base URLGCP Europe West 3 (default)`Region::GCP_EUROPE_WEST3``https://api.tinybird.co`GCP Europe West 2`Region::GCP_EUROPE_WEST2``https://api.europe-west2.gcp.tinybird.co`GCP US East 4`Region::GCP_US_EAST4``https://api.us-east.tinybird.co`GCP North America`Region::GCP_NORTHAMERICA_NORTHEAST2``https://api.northamerica-northeast2.gcp.tinybird.co`AWS EU Central 1`Region::AWS_EU_CENTRAL_1``https://api.eu-central-1.aws.tinybird.co`AWS EU West 1`Region::AWS_EU_WEST_1``https://api.eu-west-1.aws.tinybird.co`AWS US East 1`Region::AWS_US_EAST_1``https://api.us-east.aws.tinybird.co`AWS US West 2`Region::AWS_US_WEST_2``https://api.us-west-2.aws.tinybird.co`Local`Region::LOCAL``http://localhost:7181`Configuration
-------------

[](#configuration)

```
use Brd6\TinybirdSdk\Client;
use Brd6\TinybirdSdk\ClientOptions;
use Brd6\TinybirdSdk\Enum\Region;

$options = (new ClientOptions())
    ->setToken(getenv('TINYBIRD_TOKEN'))
    ->setRegion(Region::AWS_EU_CENTRAL_1)
    ->setTimeout(120)
    ->setCompression(true)
    ->setRetryMaxRetries(5)
    ->setRetryDelayMs(1000)
    ->setRetryBackoffMultiplier(3);

$tinybird = new Client($options);
```

OptionDefaultDescription`token``''`Tinybird API token`region``Region::GCP_EUROPE_WEST3`API region`baseUrl``https://api.tinybird.co`Custom API endpoint`timeout``60`Request timeout in seconds`compression``false`Enable gzip compression`apiVersion``v0`API version`httpClient`auto-discoveredCustom PSR-18 HTTP client`retryMaxRetries``3`Maximum retry attempts`retryDelayMs``2000`Initial retry delay (ms)`retryBackoffMultiplier``2`Backoff multiplierAPI Reference
-------------

[](#api-reference)

EndpointMethods`analyze()``analyzeContent()`, `analyzeRecords()`, `analyzeUrl()``events()``send()`, `sendRaw()`, `sendJson()``dataSources()``list()`, `retrieve()`, `quarantine()``query()``sql()`, `batchSql()``pipes()``list()`, `retrieve()`, `query()`, `batchQuery()`, `getData()`, `explain()``jobs()``list()`, `retrieve()`, `cancel()``variables()``list()`, `retrieve()`, `create()`, `update()`, `remove()``tokens()``list()`, `retrieve()`, `create()`, `createJwt()`, `update()`, `refresh()`, `remove()``sinkPipes()``create()`, `remove()`, `trigger()`, `getS3Settings()`, `getGcsCredentials()`Examples
--------

[](#examples)

See the [examples](./examples) directory for complete working examples:

- [Quick Start](./examples/quick-start) — Basic SDK usage
- [Analyze API](./examples/analyze) — Schema inference
- [Batch Queries](./examples/batch-queries) — Concurrent query execution
- [Data Sources](./examples/datasources) — List and inspect Data Sources
- [Events API](./examples/events) — High-frequency ingestion
- [Jobs API](./examples/jobs) — Monitor background jobs
- [Pipes API](./examples/pipes) — Query API Endpoints
- [Tokens API](./examples/tokens) — Token management
- [Variables API](./examples/variables) — Environment variables

Documentation
-------------

[](#documentation)

- [Tinybird API Reference](https://www.tinybird.co/docs/api-reference)
- [Tinybird Forward Documentation](https://www.tinybird.co/docs/forward)

Contributing
------------

[](#contributing)

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance72

Regular maintenance activity

Popularity9

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity37

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

3

Last Release

156d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f007c1c65f0c50524a653493449ebf36a777c9decd9b7603eaa3ceb4fcebb2c2?d=identicon)[brd6](/maintainers/brd6)

---

Top Contributors

[![brd6](https://avatars.githubusercontent.com/u/15201127?v=4)](https://github.com/brd6 "brd6 (11 commits)")

---

Tags

phptinybirdtinybird-apitinybird-sdkphpanalyticstinybirdtinybird-sdktinybird-api

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Psalm

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/brd6-tinybird-sdk-php/health.svg)

```
[![Health](https://phpackages.com/badges/brd6-tinybird-sdk-php/health.svg)](https://phpackages.com/packages/brd6-tinybird-sdk-php)
```

###  Alternatives

[openai-php/client

OpenAI PHP is a supercharged PHP API client that allows you to interact with the Open AI API

5.8k22.6M232](/packages/openai-php-client)[phpro/http-tools

HTTP tools for developing more consistent HTTP implementations.

28137.8k](/packages/phpro-http-tools)[brd6/notion-sdk-php

Notion SDK for PHP

5918.0k](/packages/brd6-notion-sdk-php)[theodo-group/llphant

LLPhant is a library to help you build Generative AI applications.

1.5k311.5k5](/packages/theodo-group-llphant)[mozex/anthropic-php

Anthropic PHP is a supercharged community-maintained PHP API client that allows you to interact with Anthropic API.

46365.1k13](/packages/mozex-anthropic-php)[darthsoup/php-whmcs-api

WHMCS API client for PHP

2317.3k4](/packages/darthsoup-php-whmcs-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)