> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chucky.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Session

> PHP SDK session reference

<Warning>
  **Community Maintained** - This SDK is functional but receives limited maintenance.
  For production use, we recommend the [TypeScript SDK](/sdk/javascript/client) or [Python SDK](/sdk/python/client).
</Warning>

## Creating a Session

```php theme={null}
<?php

use ChuckyCloud\Sdk\Types\SessionOptions;
use ChuckyCloud\Sdk\Types\Model;

$session = $client->createSession(new SessionOptions(
    model: Model::CLAUDE_SONNET,
    maxTurns: 10,
    systemPrompt: 'You are a helpful assistant.',
));
```

## SessionOptions

| Option                   | Type             | Default         | Description                |
| ------------------------ | ---------------- | --------------- | -------------------------- |
| `model`                  | `Model`          | `CLAUDE_SONNET` | Model to use               |
| `fallbackModel`          | `Model\|null`    | `null`          | Fallback model             |
| `systemPrompt`           | `string\|null`   | `null`          | System prompt              |
| `maxTurns`               | `int\|null`      | `null`          | Maximum conversation turns |
| `maxBudgetUsd`           | `float\|null`    | `null`          | Maximum budget in USD      |
| `maxThinkingTokens`      | `int\|null`      | `null`          | Maximum thinking tokens    |
| `tools`                  | `array\|null`    | `null`          | Tool definitions           |
| `mcpServers`             | `array\|null`    | `null`          | MCP server definitions     |
| `permissionMode`         | `PermissionMode` | `DEFAULT`       | Permission mode            |
| `outputFormat`           | `string\|null`   | `null`          | Output format              |
| `includePartialMessages` | `bool`           | `false`         | Include partial messages   |
| `env`                    | `array\|null`    | `null`          | Environment variables      |

## Available Models

```php theme={null}
use ChuckyCloud\Sdk\Types\Model;

Model::CLAUDE_SONNET    // claude-sonnet-4-5-20250929
Model::CLAUDE_HAIKU     // claude-haiku-4-5-20251001
Model::CLAUDE_OPUS      // claude-opus-4-20250514
```

## Methods

### connect

Connect to the server and initialize the session.

```php theme={null}
$session->connect()->then(function () {
    echo "Connected!\n";
});
```

### send

Send a message to Claude.

```php theme={null}
$session->send('What is 2 + 2?')->then(function () {
    echo "Message sent!\n";
});
```

### receive

Receive the next message.

```php theme={null}
$session->receive()->then(function ($msg) {
    // Handle message
});
```

### close

Close the session.

```php theme={null}
$session->close();
```

### getId

Get the session ID.

```php theme={null}
$id = $session->getId();
```

### getState

Get the current session state.

```php theme={null}
$state = $session->getState();
```

## Session States

```php theme={null}
use ChuckyCloud\Sdk\Types\SessionState;

SessionState::IDLE           // Not connected
SessionState::INITIALIZING   // Connecting
SessionState::READY          // Ready to send
SessionState::PROCESSING     // Processing message
SessionState::WAITING_TOOL   // Waiting for tool result
SessionState::COMPLETED      // Session ended
SessionState::ERROR          // Error occurred
```

## Event Handlers

```php theme={null}
use ChuckyCloud\Sdk\Client\SessionEventHandlers;

$handlers = new SessionEventHandlers();
$handlers->onMessage = fn($msg) => handleMessage($msg);
$handlers->onError = fn(\Exception $e) => handleError($e);
$handlers->onClose = fn() => echo "Session closed\n";

$session->on($handlers);
```

## Message Types

### AssistantMessage

Message from Claude.

```php theme={null}
use ChuckyCloud\Sdk\Types\AssistantMessage;

if ($msg instanceof AssistantMessage) {
    $text = $msg->getText();
    $model = $msg->model;
    $sessionId = $msg->sessionId;
}
```

### ResultMessage

Final result of the conversation.

```php theme={null}
use ChuckyCloud\Sdk\Types\ResultMessage;

if ($msg instanceof ResultMessage) {
    echo "Result: {$msg->result}\n";
    echo "Cost: \${$msg->totalCostUsd}\n";
    echo "Turns: {$msg->numTurns}\n";
    echo "Duration: {$msg->durationMs}ms\n";
    echo "Error: " . ($msg->isError ? 'yes' : 'no') . "\n";
}
```

### SystemMessage

System events.

```php theme={null}
use ChuckyCloud\Sdk\Types\SystemMessage;
use ChuckyCloud\Sdk\Types\SystemSubtype;

if ($msg instanceof SystemMessage) {
    switch ($msg->subtype) {
        case SystemSubtype::INIT:
            echo "Session initialized: {$msg->sessionId}\n";
            break;
        case SystemSubtype::TURN_START:
            echo "Turn started\n";
            break;
        case SystemSubtype::TURN_END:
            echo "Turn ended\n";
            break;
    }
}
```

### ErrorMessage

Error messages.

```php theme={null}
use ChuckyCloud\Sdk\Types\ErrorMessage;

if ($msg instanceof ErrorMessage) {
    echo "Error: {$msg->message}\n";
    echo "Code: {$msg->errorCode}\n";
}
```

### ControlMessage

Control messages.

```php theme={null}
use ChuckyCloud\Sdk\Types\ControlMessage;
use ChuckyCloud\Sdk\Types\ControlAction;

if ($msg instanceof ControlMessage) {
    if ($msg->action === ControlAction::READY) {
        echo "Ready!\n";
    }
}
```

## Full Example with Message Loop

```php theme={null}
<?php

$session->connect()->then(function () use ($session, $client) {
    $session->send('Tell me a joke')->then(function () use ($session, $client) {
        $receiveNext = function () use (&$receiveNext, $session, $client) {
            $session->receive()->then(function ($msg) use (&$receiveNext, $session, $client) {
                if ($msg instanceof SystemMessage) {
                    echo "[System] {$msg->subtype->value}\n";
                }

                if ($msg instanceof AssistantMessage) {
                    $text = $msg->getText();
                    if ($text) {
                        echo "[Assistant] {$text}\n";
                    }
                }

                if ($msg instanceof ResultMessage) {
                    echo "\n=== Result ===\n";
                    echo "Answer: {$msg->result}\n";
                    echo "Cost: \${$msg->totalCostUsd}\n";
                    $session->close();
                    $client->stop();
                    return;
                }

                $receiveNext();
            });
        };

        $receiveNext();
    });
});

$client->run();
```

## Resuming Sessions

Resume an existing session:

```php theme={null}
$session = $client->resumeSession($sessionId, new SessionOptions(
    model: Model::CLAUDE_SONNET,
));

$session->connect()->then(function () use ($session) {
    $session->send('Continue from where we left off')->then(function () {
        // Handle response
    });
});
```

## Multi-turn Conversations

```php theme={null}
function chat(Session $session, string $message): void
{
    global $client;

    $session->send($message)->then(function () use ($session, $client) {
        $receiveNext = function () use (&$receiveNext, $session, $client) {
            $session->receive()->then(function ($msg) use (&$receiveNext, $session, $client) {
                if ($msg instanceof AssistantMessage) {
                    echo $msg->getText() . "\n";
                }

                if ($msg instanceof ResultMessage) {
                    // Ready for next message
                    return;
                }

                $receiveNext();
            });
        };
        $receiveNext();
    });
}

// Usage
chat($session, 'First message');
chat($session, 'Follow-up question');
```