{"id":36964467,"url":"https://github.com/brd6/tinybird-sdk-php","last_synced_at":"2026-01-13T19:35:20.293Z","repository":{"id":328200648,"uuid":"1113861915","full_name":"brd6/tinybird-sdk-php","owner":"brd6","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-11T18:18:28.000Z","size":90,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-12T20:45:26.583Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brd6.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-10T15:09:52.000Z","updated_at":"2025-12-11T18:18:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/brd6/tinybird-sdk-php","commit_stats":null,"previous_names":["brd6/tinybird-sdk-php"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/brd6/tinybird-sdk-php","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brd6%2Ftinybird-sdk-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brd6%2Ftinybird-sdk-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brd6%2Ftinybird-sdk-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brd6%2Ftinybird-sdk-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brd6","download_url":"https://codeload.github.com/brd6/tinybird-sdk-php/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brd6%2Ftinybird-sdk-php/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28397826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-13T19:35:19.505Z","updated_at":"2026-01-13T19:35:20.278Z","avatar_url":"https://github.com/brd6.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cstrong\u003eTinybird SDK for PHP\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/brd6/tinybird-sdk-php\"\u003e\u003cimg src=\"https://img.shields.io/badge/source-brd6/tinybird--sdk--php-blue.svg?style=flat-square\" alt=\"Source Code\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://packagist.org/packages/brd6/tinybird-sdk-php\"\u003e\u003cimg src=\"https://img.shields.io/packagist/v/brd6/tinybird-sdk-php.svg?style=flat-square\u0026label=release\" alt=\"Download Package\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://php.net\"\u003e\u003cimg src=\"https://img.shields.io/packagist/php-v/brd6/tinybird-sdk-php.svg?style=flat-square\u0026colorB=%238892BF\" alt=\"PHP Programming Language\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/brd6/tinybird-sdk-php/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/packagist/l/brd6/tinybird-sdk-php.svg?style=flat-square\u0026colorB=darkcyan\" alt=\"Read License\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/brd6/tinybird-sdk-php/actions/workflows/continuous-integration.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/brd6/tinybird-sdk-php/.github/workflows/continuous-integration.yml?branch=main\u0026style=flat-square\u0026logo=github\" alt=\"Build Status\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nPHP 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.\n\n## Synopsis\n\n```php\n// Ingest → Query → Results\n$tinybird = Client::create('p.your_token');\n$tinybird-\u003eevents()-\u003esend('clicks', ['user' =\u003e 'alice', 'page' =\u003e '/home']);\n$result = $tinybird-\u003equery()-\u003esql('SELECT count() FROM clicks');\n// → {\"data\":[{\"count()\":1}],\"rows\":1}\n```\n\n## Features\n\n- **High-frequency ingestion** — Send millions of events per second via Events API\n- **Schema generation** — Analyze files to generate Data Source schemas\n- **Sub-second queries** — Execute SQL queries with instant results\n- **Concurrent requests** — Batch multiple queries for parallel execution\n- **Multi-region support** — EU, US, AWS, GCP, and custom deployments\n- **Built-in retry logic** — Automatic retry with exponential backoff\n- **PSR-18 compatible** — Works with Symfony, Guzzle, or any HTTP client\n- **Type-safe resources** — Full PHP 8.1+ support with strict types\n\n## Installation\n\nInstall this package using [Composer](https://getcomposer.org):\n\n```bash\ncomposer require brd6/tinybird-sdk-php\n```\n\nThis 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:\n\n```bash\ncomposer require brd6/tinybird-sdk-php symfony/http-client nyholm/psr7\n```\n\n## Quick Start\n\n```php\nuse Brd6\\TinybirdSdk\\Client;\n\n// Create client (uses EU region by default)\n$tinybird = Client::create('p.your_token_here');\n\n// Ingest events\n$tinybird-\u003eevents()-\u003esend('events', [\n    ['timestamp' =\u003e '2025-01-01 00:00:00', 'event' =\u003e 'page_view', 'user_id' =\u003e 'user_123'],\n    ['timestamp' =\u003e '2025-01-01 00:00:01', 'event' =\u003e 'click', 'user_id' =\u003e 'user_456'],\n]);\n\n// Query with SQL\n$result = $tinybird-\u003equery()-\u003esql('SELECT count() FROM events');\n\n// Call a Pipe endpoint\n$result = $tinybird-\u003epipes()-\u003equery('analytics_endpoint', ['date_from' =\u003e '2025-01-01']);\n```\n\n### Region Selection\n\n```php\nuse Brd6\\TinybirdSdk\\Client;\nuse Brd6\\TinybirdSdk\\Enum\\Region;\n\n// US East\n$tinybird = Client::forRegion('p.your_token', Region::GCP_US_EAST4);\n\n// AWS EU Central\n$tinybird = Client::forRegion('p.your_token', Region::AWS_EU_CENTRAL_1);\n\n// Tinybird Local\n$tinybird = Client::local('your_local_token');\n\n// Custom port\n$tinybird = Client::local('your_local_token', 8080);\n```\n\n### Custom Endpoint\n\nFor private deployments or custom domains:\n\n```php\nuse Brd6\\TinybirdSdk\\Client;\nuse Brd6\\TinybirdSdk\\ClientOptions;\n\n$options = (new ClientOptions())\n    -\u003esetToken('your_token')\n    -\u003esetBaseUrl('https://your-custom-endpoint.com');\n\n$tinybird = new Client($options);\n```\n\n## Usage\n\n### Analyze API\n\nAnalyze files to generate Tinybird Data Source schemas. Useful before creating `.datasource` files.\n\n```php\n// Analyze NDJSON records\n$result = $tinybird-\u003eanalyze()-\u003eanalyzeRecords([\n    ['timestamp' =\u003e '2025-01-01 00:00:00', 'event' =\u003e 'page_view', 'user_id' =\u003e 'user_123'],\n    ['timestamp' =\u003e '2025-01-01 00:00:01', 'event' =\u003e 'click', 'user_id' =\u003e 'user_456'],\n]);\n\n// Get the generated schema (ready for .datasource files)\necho $result-\u003egetSchema();\n// Output: timestamp DateTime `json:$.timestamp`, event String `json:$.event`, ...\n\n// Inspect analyzed columns\nforeach ($result-\u003ecolumns as $col) {\n    echo \"{$col-\u003ename}: {$col-\u003erecommendedType}\";\n    if ($col-\u003epresentPct \u003c 1) {\n        echo \" (nullable)\";\n    }\n}\n\n// Analyze a remote file\n$result = $tinybird-\u003eanalyze()-\u003eanalyzeUrl('https://example.com/data.ndjson');\n\n// Analyze raw content\n$result = $tinybird-\u003eanalyze()-\u003eanalyzeContent($csvContent);\n```\n\n### Events API\n\nHigh-frequency data ingestion optimized for real-time analytics. This is the recommended way to ingest data in Tinybird Forward workspaces.\n\n```php\n// Send single event\n$result = $tinybird-\u003eevents()-\u003esend('events', [\n    'timestamp' =\u003e '2025-01-01 00:00:00',\n    'event' =\u003e 'page_view',\n    'user_id' =\u003e 'user_123',\n]);\n\n// Send batch events\n$result = $tinybird-\u003eevents()-\u003esend('events', [\n    ['timestamp' =\u003e '2025-01-01 00:00:00', 'event' =\u003e 'page_view', 'user_id' =\u003e 'user_123'],\n    ['timestamp' =\u003e '2025-01-01 00:00:01', 'event' =\u003e 'click', 'user_id' =\u003e 'user_456'],\n]);\n\n// Check result\necho $result-\u003esuccessfulRows;   // Rows ingested\necho $result-\u003equarantinedRows;  // Rows failed validation\n\n// Send raw NDJSON\n$tinybird-\u003eevents()-\u003esendRaw('events', $ndjsonString);\n```\n\n### Data Sources\n\nRead Data Source information and metadata.\n\n```php\n// List all Data Sources\n$datasources = $tinybird-\u003edataSources()-\u003elist();\n\nforeach ($datasources as $ds) {\n    echo $ds-\u003ename;\n    echo $ds-\u003egetRowCount();\n    echo $ds-\u003egetBytes();\n}\n\n// Get Data Source details\n$info = $tinybird-\u003edataSources()-\u003eretrieve('events');\n\necho $info-\u003eid;\necho $info-\u003ename;\necho $info-\u003etype;\necho $info-\u003ecreatedAt;\n\n// Access columns\nforeach ($info-\u003ecolumns as $column) {\n    echo $column-\u003ename;\n    echo $column-\u003etype;\n}\n\n// Get quarantine data\n$quarantine = $tinybird-\u003edataSources()-\u003equarantine('events');\n```\n\n\u003e **Note:** For schema changes, use the Tinybird CLI (`tb deploy`). See [Tinybird Forward documentation](https://www.tinybird.co/docs/forward).\n\n### Query API\n\nExecute raw SQL queries against your Data Sources.\n\n```php\n// Simple query\n$result = $tinybird-\u003equery()-\u003esql('SELECT count() FROM events');\n\necho $result-\u003erows;\necho $result-\u003edata[0]['count()'];\n\n// Query with parameters\n$result = $tinybird-\u003equery()-\u003esql(\n    'SELECT * FROM events WHERE user_id = {user_id:String} LIMIT {limit:Int32}',\n    ['user_id' =\u003e 'user_123', 'limit' =\u003e 100]\n);\n\n// Access results\nforeach ($result-\u003edata as $row) {\n    echo $row['event'];\n}\n\n// Query statistics\necho $result-\u003egetElapsedTime();\necho $result-\u003egetRowsRead();\necho $result-\u003egetBytesRead();\n```\n\n#### Batch Queries\n\nExecute multiple SQL queries concurrently for better performance:\n\n```php\n// Run multiple queries in parallel\n$results = $tinybird-\u003equery()-\u003ebatchSql([\n    'total_users' =\u003e 'SELECT count() FROM users',\n    'active_today' =\u003e 'SELECT count() FROM events WHERE date = today()',\n    'revenue' =\u003e 'SELECT sum(amount) FROM orders',\n]);\n\n// Access individual results\nforeach ($results as $key =\u003e $result) {\n    if ($result-\u003eisSuccess()) {\n        echo \"{$key}: \" . $result-\u003egetData()-\u003edata[0];\n    } else {\n        echo \"{$key} failed: \" . $result-\u003egetException()-\u003egetMessage();\n    }\n}\n\n// Or get data directly\n$totalUsers = $results['total_users']-\u003egetData()-\u003edata[0]['count()'];\n```\n\n### Pipes API\n\nQuery published API Endpoints and list Pipes.\n\n```php\n// List Pipes\n$pipes = $tinybird-\u003epipes()-\u003elist();\n\n// Query a Pipe endpoint\n$result = $tinybird-\u003epipes()-\u003equery('my_analytics_endpoint', [\n    'start_date' =\u003e '2025-01-01',\n    'end_date' =\u003e '2025-12-31',\n    'limit' =\u003e 1000,\n]);\n\nforeach ($result-\u003edata as $row) {\n    // Process results\n}\n```\n\n#### Batch Pipe Queries\n\nQuery multiple Pipe endpoints concurrently:\n\n```php\n// Simple: key is pipe name\n$results = $tinybird-\u003epipes()-\u003ebatchQuery([\n    'user_stats' =\u003e ['date' =\u003e '2025-01-01'],\n    'event_counts' =\u003e ['type' =\u003e 'click'],\n]);\n\n// Query same pipe multiple times using # alias\n$results = $tinybird-\u003epipes()-\u003ebatchQuery([\n    'user_stats#jan' =\u003e ['date' =\u003e '2025-01-01'],\n    'user_stats#feb' =\u003e ['date' =\u003e '2025-02-01'],\n    'user_stats#mar' =\u003e ['date' =\u003e '2025-03-01'],\n]);\n\n// Handle results with error isolation\nforeach ($results as $key =\u003e $result) {\n    if ($result-\u003eisSuccess()) {\n        $data = $result-\u003egetData();\n        echo \"{$key}: {$data-\u003erows} rows\";\n    } else {\n        // Individual failures don't affect other queries\n        echo \"{$key} failed: \" . $result-\u003egetException()-\u003egetMessage();\n    }\n}\n```\n\n### Jobs API\n\nMonitor and manage background jobs (imports, populates, copies).\n\n```php\nuse Brd6\\TinybirdSdk\\RequestParameters\\ListJobsParams;\nuse Brd6\\TinybirdSdk\\Enum\\JobStatus;\n\n// List recent jobs\n$jobs = $tinybird-\u003ejobs()-\u003elist();\n\n// Filter by status\n$jobs = $tinybird-\u003ejobs()-\u003elist(new ListJobsParams(status: JobStatus::DONE));\n\n// Get job details\n$job = $tinybird-\u003ejobs()-\u003eretrieve($jobId);\necho $job-\u003estatus; // waiting, working, done, error\n\n// Cancel a running job\n$tinybird-\u003ejobs()-\u003ecancel($jobId);\n```\n\n### Environment Variables API\n\nManage workspace variables for use in Pipes.\n\n```php\n// List all variables\n$vars = $tinybird-\u003evariables()-\u003elist();\n\n// Create a variable\n$var = $tinybird-\u003evariables()-\u003ecreate('API_KEY', 'secret_value');\n\n// Update a variable\n$tinybird-\u003evariables()-\u003eupdate('API_KEY', 'new_value');\n\n// Delete a variable\n$tinybird-\u003evariables()-\u003eremove('API_KEY');\n```\n\n### Tokens API\n\nManage workspace tokens for authentication.\n\n```php\nuse Brd6\\TinybirdSdk\\RequestParameters\\CreateTokenParams;\n\n// List all tokens\n$tokens = $tinybird-\u003etokens()-\u003elist();\n\n// Create a token with scopes\n$token = $tinybird-\u003etokens()-\u003ecreate(new CreateTokenParams(\n    name: 'my_token',\n    scopes: ['PIPES:READ', 'DATASOURCES:READ'],\n));\n\n// Refresh (rotate) a token\n$newToken = $tinybird-\u003etokens()-\u003erefresh('my_token');\n\n// Delete a token\n$tinybird-\u003etokens()-\u003eremove('my_token');\n```\n\n### Sink Pipes API\n\nExport data to object stores (S3, GCS).\n\n```php\nuse Brd6\\TinybirdSdk\\RequestParameters\\CreateSinkParams;\n\n// Create a sink pipe\n$pipe = $tinybird-\u003esinkPipes()-\u003ecreate($pipeId, $nodeId, new CreateSinkParams(\n    connection: 's3://bucket/path',\n    path: 'exports/',\n));\n\n// Trigger a sink export\n$result = $tinybird-\u003esinkPipes()-\u003etrigger($pipeId);\n\n// Get S3 integration settings\n$settings = $tinybird-\u003esinkPipes()-\u003egetS3Settings();\n```\n\n### Error Handling\n\n```php\nuse Brd6\\TinybirdSdk\\Exception\\ApiException;\nuse Brd6\\TinybirdSdk\\Exception\\AuthenticationException;\nuse Brd6\\TinybirdSdk\\Exception\\RateLimitException;\nuse Brd6\\TinybirdSdk\\Exception\\RequestTimeoutException;\n\ntry {\n    $result = $tinybird-\u003epipes()-\u003equery('my_endpoint');\n} catch (AuthenticationException $e) {\n    // Invalid or expired token (401/403)\n    // Includes helpful suggestions for region mismatches\n} catch (RateLimitException $e) {\n    // Too many requests (429)\n    $retryAfter = $e-\u003egetRetryAfter();\n    $limit = $e-\u003egetRateLimitLimit();\n    $remaining = $e-\u003egetRateLimitRemaining();\n} catch (RequestTimeoutException $e) {\n    // Request timed out\n} catch (ApiException $e) {\n    // Other API errors\n    $code = $e-\u003egetCode();\n    $message = $e-\u003egetMessage();\n    $response = $e-\u003egetResponse();\n}\n```\n\n## Regions\n\n| Region | Enum | API Base URL |\n|--------|------|--------------|\n| GCP Europe West 3 (default) | `Region::GCP_EUROPE_WEST3` | `https://api.tinybird.co` |\n| GCP Europe West 2 | `Region::GCP_EUROPE_WEST2` | `https://api.europe-west2.gcp.tinybird.co` |\n| GCP US East 4 | `Region::GCP_US_EAST4` | `https://api.us-east.tinybird.co` |\n| GCP North America | `Region::GCP_NORTHAMERICA_NORTHEAST2` | `https://api.northamerica-northeast2.gcp.tinybird.co` |\n| AWS EU Central 1 | `Region::AWS_EU_CENTRAL_1` | `https://api.eu-central-1.aws.tinybird.co` |\n| AWS EU West 1 | `Region::AWS_EU_WEST_1` | `https://api.eu-west-1.aws.tinybird.co` |\n| AWS US East 1 | `Region::AWS_US_EAST_1` | `https://api.us-east.aws.tinybird.co` |\n| AWS US West 2 | `Region::AWS_US_WEST_2` | `https://api.us-west-2.aws.tinybird.co` |\n| Local | `Region::LOCAL` | `http://localhost:7181` |\n\n## Configuration\n\n```php\nuse Brd6\\TinybirdSdk\\Client;\nuse Brd6\\TinybirdSdk\\ClientOptions;\nuse Brd6\\TinybirdSdk\\Enum\\Region;\n\n$options = (new ClientOptions())\n    -\u003esetToken(getenv('TINYBIRD_TOKEN'))\n    -\u003esetRegion(Region::AWS_EU_CENTRAL_1)\n    -\u003esetTimeout(120)\n    -\u003esetCompression(true)\n    -\u003esetRetryMaxRetries(5)\n    -\u003esetRetryDelayMs(1000)\n    -\u003esetRetryBackoffMultiplier(3);\n\n$tinybird = new Client($options);\n```\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `token` | `''` | Tinybird API token |\n| `region` | `Region::GCP_EUROPE_WEST3` | API region |\n| `baseUrl` | `https://api.tinybird.co` | Custom API endpoint |\n| `timeout` | `60` | Request timeout in seconds |\n| `compression` | `false` | Enable gzip compression |\n| `apiVersion` | `v0` | API version |\n| `httpClient` | auto-discovered | Custom PSR-18 HTTP client |\n| `retryMaxRetries` | `3` | Maximum retry attempts |\n| `retryDelayMs` | `2000` | Initial retry delay (ms) |\n| `retryBackoffMultiplier` | `2` | Backoff multiplier |\n\n## API Reference\n\n| Endpoint | Methods |\n|----------|---------|\n| `analyze()` | `analyzeContent()`, `analyzeRecords()`, `analyzeUrl()` |\n| `events()` | `send()`, `sendRaw()`, `sendJson()` |\n| `dataSources()` | `list()`, `retrieve()`, `quarantine()` |\n| `query()` | `sql()`, `batchSql()` |\n| `pipes()` | `list()`, `retrieve()`, `query()`, `batchQuery()`, `getData()`, `explain()` |\n| `jobs()` | `list()`, `retrieve()`, `cancel()` |\n| `variables()` | `list()`, `retrieve()`, `create()`, `update()`, `remove()` |\n| `tokens()` | `list()`, `retrieve()`, `create()`, `createJwt()`, `update()`, `refresh()`, `remove()` |\n| `sinkPipes()` | `create()`, `remove()`, `trigger()`, `getS3Settings()`, `getGcsCredentials()` |\n\n## Examples\n\nSee the [examples](./examples) directory for complete working examples:\n\n- [Quick Start](./examples/quick-start) — Basic SDK usage\n- [Analyze API](./examples/analyze) — Schema inference\n- [Batch Queries](./examples/batch-queries) — Concurrent query execution\n- [Data Sources](./examples/datasources) — List and inspect Data Sources\n- [Events API](./examples/events) — High-frequency ingestion\n- [Jobs API](./examples/jobs) — Monitor background jobs\n- [Pipes API](./examples/pipes) — Query API Endpoints\n- [Tokens API](./examples/tokens) — Token management\n- [Variables API](./examples/variables) — Environment variables\n\n## Documentation\n\n- [Tinybird API Reference](https://www.tinybird.co/docs/api-reference)\n- [Tinybird Forward Documentation](https://www.tinybird.co/docs/forward)\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrd6%2Ftinybird-sdk-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrd6%2Ftinybird-sdk-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrd6%2Ftinybird-sdk-php/lists"}