Skip to content
New site — Virtual Media Folders now has its own home.Visit vmf.soderlind.no →

Native Extension API Reference

The native API exposes the Rust extension directly to PHP. Complex inputs and outputs are JSON strings so the PHP surface can track the Copilot SDK without introducing many PHP value objects.

Use this API when you need raw status calls, model listing, manual session control, streaming event polling, or arbitrary SDK JSON-RPC calls.

Copilot
Symbol Type Description
copilot_sdk_version() function Returns the extension crate version.
Copilot\Client class Starts and controls the Copilot CLI server connection.
Copilot\Session class Represents a Copilot conversation session.
use Copilot\Client;
$client = new Client(json_encode([
'cwd' => getcwd(),
'githubToken' => getenv('GITHUB_COPILOT_TOKEN'),
'useLoggedInUser' => false,
'copilotHome' => __DIR__ . '/../var/copilot',
], JSON_THROW_ON_ERROR));
$session = $client->createSession(json_encode([
'model' => 'gpt-5',
'streaming' => true,
'permissionPolicy' => 'deny_all',
], JSON_THROW_ON_ERROR));
$event = json_decode(
$session->sendAndWaitJson('Explain this project in one paragraph.'),
true,
512,
JSON_THROW_ON_ERROR
);
$session->disconnect();
$client->stop();
function copilot_sdk_version(): string

Returns the extension crate version.

Returns a semantic version string.

echo copilot_sdk_version(), PHP_EOL;

Starts the Copilot CLI server and opens a client connection.

public function __construct(?string $optionsJson = null)

Creates a Copilot client from optional JSON-encoded client options.

Name Type Description
$optionsJson ?string JSON object with client options.
Exception Condition
Throwable JSON is invalid, options are invalid, or the Copilot CLI server cannot start.
$client = new Copilot\Client(json_encode([
'githubToken' => getenv('GITHUB_COPILOT_TOKEN'),
'useLoggedInUser' => false,
'copilotHome' => __DIR__ . '/../var/copilot',
'cwd' => getcwd(),
], JSON_THROW_ON_ERROR));
public function ping(?string $message = null): string

Pings the Copilot server.

Name Type Description
$message ?string Optional ping message.

Returns a JSON string.

$response = json_decode($client->ping('hello'), true, 512, JSON_THROW_ON_ERROR);
public function modelsJson(): string

Returns available model metadata.

Returns a JSON string containing model metadata.

$models = json_decode($client->modelsJson(), true, 512, JSON_THROW_ON_ERROR);
public function statusJson(): string

Returns general Copilot server status.

Returns a JSON string.

$status = json_decode($client->statusJson(), true, 512, JSON_THROW_ON_ERROR);
public function authStatusJson(): string

Returns authentication status.

Returns a JSON string.

$auth = json_decode($client->authStatusJson(), true, 512, JSON_THROW_ON_ERROR);
public function callJson(string $method, ?string $paramsJson = null): string

Calls an arbitrary Copilot SDK JSON-RPC method.

Name Type Description
$method string SDK JSON-RPC method name.
$paramsJson ?string JSON-encoded params object or array.

Returns a JSON string.

$result = json_decode(
$client->callJson('status', json_encode([], JSON_THROW_ON_ERROR)),
true,
512,
JSON_THROW_ON_ERROR
);
public function createSession(?string $configJson = null): Copilot\Session

Creates a new Copilot session.

Name Type Description
$configJson ?string JSON-encoded session configuration.

Returns a Copilot\Session instance.

$session = $client->createSession(json_encode([
'model' => 'gpt-5',
'permissionPolicy' => 'deny_all',
], JSON_THROW_ON_ERROR));
public function resumeSession(string $sessionId, ?string $configJson = null): Copilot\Session

Resumes an existing session id.

Name Type Description
$sessionId string Session id to resume.
$configJson ?string JSON-encoded session configuration.

Returns a Copilot\Session instance.

$session = $client->resumeSession($sessionId, json_encode([
'permissionPolicy' => 'deny_all',
], JSON_THROW_ON_ERROR));
public function stop(): void

Stops the Copilot client/server. Calling it more than once is safe.

$client->stop();

Represents an active or resumed Copilot conversation session.

public function id(): string

Returns the session id.

Returns the session id string.

echo $session->id(), PHP_EOL;
public function workspacePath(): ?string

Returns the session workspace path when one is known.

Returns the workspace path or null.

$workspacePath = $session->workspacePath();
public function remoteUrl(): ?string

Returns the remote URL when one is known.

Returns the remote URL or null.

$remoteUrl = $session->remoteUrl();
public function capabilitiesJson(): string

Returns session capabilities.

Returns a JSON string.

$capabilities = json_decode($session->capabilitiesJson(), true, 512, JSON_THROW_ON_ERROR);
public function send(string $prompt, ?string $optionsJson = null): string

Sends or enqueues a prompt.

Name Type Description
$prompt string Prompt text.
$optionsJson ?string JSON-encoded message options.

Returns the message id.

$messageId = $session->send('List the top-level PHP files.', json_encode([
'mode' => 'enqueue',
], JSON_THROW_ON_ERROR));
public function sendAndWaitJson(string $prompt, ?string $optionsJson = null): string

Sends a prompt, waits for the next response event, and returns it.

Name Type Description
$prompt string Prompt text.
$optionsJson ?string JSON-encoded message options.

Returns a JSON string containing the next response event.

$event = json_decode($session->sendAndWaitJson('Explain README.md.', json_encode([
'timeoutSeconds' => 90,
], JSON_THROW_ON_ERROR)), true, 512, JSON_THROW_ON_ERROR);
public function messagesJson(): string

Returns session messages.

Returns a JSON string.

$messages = json_decode($session->messagesJson(), true, 512, JSON_THROW_ON_ERROR);
public function nextEventJson(?int $timeoutMs = null): ?string

Returns the next streaming event, or null when no event arrives before the timeout.

Name Type Description
$timeoutMs ?int Wait timeout in milliseconds.

Returns a JSON event string or null.

while (($eventJson = $session->nextEventJson(250)) !== null) {
$event = json_decode($eventJson, true, 512, JSON_THROW_ON_ERROR);
var_dump($event['type'] ?? null);
}
public function abort(): void

Aborts the active Copilot operation for the session.

$session->abort();
public function setModel(string $model, ?string $optionsJson = null): void

Changes the session model.

Name Type Description
$model string Model name.
$optionsJson ?string JSON-encoded set-model options.
$session->setModel('gpt-5', json_encode([
'reasoningEffort' => 'medium',
], JSON_THROW_ON_ERROR));
public function disconnect(): void

Disconnects the session. Calling it more than once is safe.

$session->disconnect();