Native Extension API Reference

Native Extension API Reference

Summary

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.

Namespace

Copilot

Symbols

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.

Synopsis

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();

Global Function

copilot_sdk_version()

function copilot_sdk_version(): string

Returns the extension crate version.

Return Value

Returns a semantic version string.

Example

echo copilot_sdk_version(), PHP_EOL;

Copilot\Client

Description

Starts the Copilot CLI server and opens a client connection.

__construct()

public function __construct(?string $optionsJson = null)

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

Parameters

Name	Type	Description
$optionsJson	?string	JSON object with client options.

Throws

Exception	Condition
Throwable	JSON is invalid, options are invalid, or the Copilot CLI server cannot start.

Example

$client = new Copilot\Client(json_encode([
    'githubToken' => getenv('GITHUB_COPILOT_TOKEN'),
    'useLoggedInUser' => false,
    'copilotHome' => __DIR__ . '/../var/copilot',
    'cwd' => getcwd(),
], JSON_THROW_ON_ERROR));

ping()

public function ping(?string $message = null): string

Pings the Copilot server.

Parameters

Name	Type	Description
$message	?string	Optional ping message.

Return Value

Returns a JSON string.

Example

$response = json_decode($client->ping('hello'), true, 512, JSON_THROW_ON_ERROR);

modelsJson()

public function modelsJson(): string

Returns available model metadata.

Return Value

Returns a JSON string containing model metadata.

Example

$models = json_decode($client->modelsJson(), true, 512, JSON_THROW_ON_ERROR);

statusJson()

public function statusJson(): string

Returns general Copilot server status.

Return Value

Returns a JSON string.

Example

$status = json_decode($client->statusJson(), true, 512, JSON_THROW_ON_ERROR);

authStatusJson()

public function authStatusJson(): string

Returns authentication status.

Return Value

Returns a JSON string.

Example

$auth = json_decode($client->authStatusJson(), true, 512, JSON_THROW_ON_ERROR);

callJson()

public function callJson(string $method, ?string $paramsJson = null): string

Calls an arbitrary Copilot SDK JSON-RPC method.

Parameters

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

Return Value

Returns a JSON string.

Example

$result = json_decode(
    $client->callJson('status', json_encode([], JSON_THROW_ON_ERROR)),
    true,
    512,
    JSON_THROW_ON_ERROR
);

createSession()

public function createSession(?string $configJson = null): Copilot\Session

Creates a new Copilot session.

Parameters

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

Return Value

Returns a Copilot\Session instance.

Example

$session = $client->createSession(json_encode([
    'model' => 'gpt-5',
    'permissionPolicy' => 'deny_all',
], JSON_THROW_ON_ERROR));

resumeSession()

public function resumeSession(string $sessionId, ?string $configJson = null): Copilot\Session

Resumes an existing session id.

Parameters

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

Return Value

Returns a Copilot\Session instance.

Example

$session = $client->resumeSession($sessionId, json_encode([
    'permissionPolicy' => 'deny_all',
], JSON_THROW_ON_ERROR));

stop()

public function stop(): void

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

Example

$client->stop();

Copilot\Session

Description

Represents an active or resumed Copilot conversation session.

id()

public function id(): string

Returns the session id.

Return Value

Returns the session id string.

Example

echo $session->id(), PHP_EOL;

workspacePath()

public function workspacePath(): ?string

Returns the session workspace path when one is known.

Return Value

Returns the workspace path or null.

Example

$workspacePath = $session->workspacePath();

remoteUrl()

public function remoteUrl(): ?string

Returns the remote URL when one is known.

Return Value

Returns the remote URL or null.

Example

$remoteUrl = $session->remoteUrl();

capabilitiesJson()

public function capabilitiesJson(): string

Returns session capabilities.

Return Value

Returns a JSON string.

Example

$capabilities = json_decode($session->capabilitiesJson(), true, 512, JSON_THROW_ON_ERROR);

send()

public function send(string $prompt, ?string $optionsJson = null): string

Sends or enqueues a prompt.

Parameters

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

Return Value

Returns the message id.

Example

$messageId = $session->send('List the top-level PHP files.', json_encode([
    'mode' => 'enqueue',
], JSON_THROW_ON_ERROR));

sendAndWaitJson()

public function sendAndWaitJson(string $prompt, ?string $optionsJson = null): string

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

Parameters

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

Return Value

Returns a JSON string containing the next response event.

Example

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

messagesJson()

public function messagesJson(): string

Returns session messages.

Return Value

Returns a JSON string.

Example

$messages = json_decode($session->messagesJson(), true, 512, JSON_THROW_ON_ERROR);

nextEventJson()

public function nextEventJson(?int $timeoutMs = null): ?string

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

Parameters

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

Return Value

Returns a JSON event string or null.

Example

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

abort()

public function abort(): void

Aborts the active Copilot operation for the session.

Example

$session->abort();

setModel()

public function setModel(string $model, ?string $optionsJson = null): void

Changes the session model.

Parameters

Name	Type	Description
$model	string	Model name.
$optionsJson	?string	JSON-encoded set-model options.

Example

$session->setModel('gpt-5', json_encode([
    'reasoningEffort' => 'medium',
], JSON_THROW_ON_ERROR));

disconnect()

public function disconnect(): void

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

Example

$session->disconnect();

See Also

• COPILOT-WRAPPER.md
• COPILOT-OPTIONS.md
• COPILOT-EXAMPLES.md

📦 Source: soderlind/ext-php-copilot · Edit on GitHub