README

Official PHP SDK for SynapCores — the AI-native database that runs SQL, vectors, RAG, and the in-database agentic runtime from a single engine.

Framework-agnostic. Use it from vanilla PHP, Symfony, WordPress, or any Composer-managed project. For a Laravel-native experience (facade, artisan commands, Eloquent vector cast, queue jobs), see synapcores/laravel.

Requirements

PHP 8.1+
ext-json
A running SynapCores engine (free CE: docker pull synapcores/community:latest)

Install

composer require synapcores/sdk

Quickstart — 30 seconds

<?php
require __DIR__ . '/vendor/autoload.php';

use SynapCores\SDK\Client;

// Option A — API key (recommended for service-to-service)
$sc = new Client([
    'host'   => 'localhost',
    'port'   => 28080,
    'apiKey' => 'aidb_…',
]);

// Option B — username/password login flow
$sc = new Client(['host' => 'localhost', 'port' => 28080,
                  'username' => 'admin', 'password' => '…']);
$sc->login();

// Run SQL — returns a typed QueryResult (iterable, countable)
$result = $sc->sql('SELECT name FROM customers WHERE id = :id', ['id' => 42]);
foreach ($result as $row) {
    echo $row['name'], PHP_EOL;
}
echo $result->scalar();              // first column of first row

What's in the box

Method	What it does
`sql(string $sql, array $params = [])`	Run SQL via `/v1/query/execute`. `:name` placeholders are substituted client-side with proper SQL escaping (the engine's REST surface doesn't parse placeholders). Returns `QueryResult`.
`embed(string $text, ?string $model = null)`	`SELECT EMBED(...)` — returns `float[]`.
`ragSearch(string $query, array $opts = [])`	Top-K similar rows from a table with a `VECTOR` column.
`agentRun(string $persona, string $task, array $opts = [])`	Fire `AGENT_RUN()` — in-DB agentic runtime. Returns `AgentRunResult`.
`importRecipe(string $url)`	Import a recipe from a URL.
`execRecipe(string $recipeId, array $params = [])`	Execute an imported recipe.
`knnSearch(string $table, array $vec, int $k = 10, array $opts = [])`	KNN against a `VECTOR` column with a literal query vector.
`login(?string $u, ?string $p)`	Exchange credentials for a JWT (only needed without API key).

Every error becomes a SynapCores\SDK\Exception\… — AuthException, QueryException, NetworkException, EnvelopeException. Catch SynapCoresException to catch them all.

Examples

RAG over your docs

$hits = $sc->ragSearch('how do I reset my password?', [
    'table'  => 'docs_chunks',
    'vecCol' => 'embedding',
    'k'      => 5,
]);
foreach ($hits as $hit) {
    printf("[%.2f] %s\n", $hit['_score'], $hit['title']);
}

In-DB agent

$out = $sc->agentRun(
    persona: 'technical_advisor',
    task:    'Summarize the support tickets opened today.'
);
echo $out->answer;

Import + run a recipe

$recipe = $sc->importRecipe('https://synapcores.com/recipes/churn-prediction.md');
$result = $sc->execRecipe($recipe->recipeId, ['cohort' => 'enterprise']);
echo "Recipe done in {$result->tookMs} ms — {$result->succeededSteps}/{$result->totalSteps} steps OK\n";

Embedding generation

$vec = $sc->embed('hello world');
echo count($vec); // 384 (MiniLM) or 768 (your configured model)

Configuration reference

Key	Type	Default	Notes
`host`	string	`localhost`	Gateway hostname
`port`	int	`28080`	Gateway port
`useHttps`	bool	`false`	Set `true` in prod
`apiKey`	string	—	`aidb_…` Bearer key (recommended)
`token`	string	—	Pre-obtained JWT (skip `login()`)
`username`	string	—	For the `login()` flow
`password`	string	—	For the `login()` flow
`timeout`	float	`30.0`	Request timeout in seconds
`database`	string	—	Sets `X-Database` header
`tenant`	string	—	Sets `X-Tenant` header
`userAgent`	string	`synapcores-php-sdk/1.0.0`
`verifyTls`	bool	`true`	Set `false` ONLY for local self-signed dev

Parameter binding — how it actually works

The engine's /v1/query/execute route does NOT parse :name, ?, or $1 placeholders server-side. The SDK substitutes :name placeholders client-side with proper SQL escaping (single-quote doubling, backslash escape, NULL/TRUE/FALSE literals, vector array literals for float[]).

What goes over the wire is fully inlined SQL — you'll never see a params field in the request body. This means:

array<string, scalar|null|float[]> is the only supported $params shape.
Untrusted user input is safe IF it's passed through $params (the SDK escapes it). Never string-concatenate user input into the SQL itself.
If a :name in the SQL has no matching key, the SDK throws QueryException — fail-fast, not silent.

// SAFE — single quotes inside the value get doubled correctly
$sc->sql('SELECT * FROM users WHERE name = :n', ['n' => "O'Brien"]);

// SAFE — vector value becomes [0.1,0.2,0.3]
$sc->sql('INSERT INTO docs (id, embedding) VALUES (:id, :v)',
         ['id' => 1, 'v' => [0.1, 0.2, 0.3]]);

Engine compatibility

Tested live against SynapCores AIDB v1.7.0.2.1-ce (current :latest, image ghcr.io/synapcores/community:latest). The SDK targets the stable /v1/* REST surface — minor engine releases should not break it.

License

MIT — see LICENSE.

synapcores / sdk

Maintainers

Package info

Statistics

Security