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

# Eventi del ciclo di vita della sessione

> Descrive come sottoscrivere gli eventi di creazione, aggiornamento, eliminazione e cambio di stato foreground della sessione in Laravel Copilot SDK.

## Eventi del ciclo di vita della sessione

Gli eventi del ciclo di vita della sessione notificano creazione, eliminazione, aggiornamento e cambi di stato foreground/background (in modalità TUI+server) della sessione.

## Tipi di evento

I 5 tipi di evento definiti nell'enum `SessionLifecycleEventType` sono i seguenti.

| Evento               | Descrizione                          |
| -------------------- | ------------------------------------ |
| `session.created`    | È stata creata una nuova sessione    |
| `session.deleted`    | Una sessione è stata eliminata       |
| `session.updated`    | Una sessione è stata aggiornata      |
| `session.foreground` | Una sessione è passata in foreground |
| `session.background` | Una sessione è passata in background |

```php theme={null}
use Revolution\Copilot\Enums\SessionLifecycleEventType;

// Ottieni il valore del tipo di evento
echo SessionLifecycleEventType::SESSION_CREATED->value; // 'session.created'
```

## Sottoscrizione degli eventi

Puoi sottoscrivere gli eventi del ciclo di vita della sessione con il metodo `onLifecycle()`.

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionLifecycleEvent;

// Ottieni il Client e sottoscrivi gli eventi del ciclo di vita
$client = Copilot::client();

// Sottoscrivi tutti gli eventi del ciclo di vita
$unsubscribe = $client->onLifecycle(function (SessionLifecycleEvent $event) {
    match ($event->type) {
        SessionLifecycleEventType::SESSION_CREATED => info("Sessione creata: {$event->sessionId}"),
        SessionLifecycleEventType::SESSION_DELETED => info("Sessione eliminata: {$event->sessionId}"),
        SessionLifecycleEventType::SESSION_FOREGROUND => info("Foreground: {$event->sessionId}"),
        SessionLifecycleEventType::SESSION_BACKGROUND => info("Background: {$event->sessionId}"),
        default => null,
    };
});

// Annulla la sottoscrizione
$unsubscribe();
```

## SessionLifecycleEvent

`SessionLifecycleEvent` è una readonly class che contiene i dettagli dell'evento del ciclo di vita.

```php theme={null}
use Revolution\Copilot\Types\SessionLifecycleEvent;
use Revolution\Copilot\Types\SessionLifecycleEventMetadata;

readonly class SessionLifecycleEvent implements Arrayable
{
    public function __construct(
        public SessionLifecycleEventType $type,  // Tipo di evento
        public string $sessionId,                 // ID sessione
        public ?SessionLifecycleEventMetadata $metadata = null,  // Metadata (assenti in caso di eliminazione)
    ) {}
}
```

### SessionLifecycleEventMetadata

Classe che contiene i metadata della sessione (non è inclusa nell'evento di eliminazione).

```php theme={null}
readonly class SessionLifecycleEventMetadata implements Arrayable
{
    public function __construct(
        public string $startTime,      // Ora di inizio della sessione
        public string $modifiedTime,   // Ora dell'ultima modifica
        public ?string $summary = null, // Riepilogo della sessione
    ) {}
}
```

## Gestione della sessione foreground

Quando sei connesso a un server in esecuzione in modalità TUI+server (`--ui-server`), puoi gestire la sessione foreground.

### Ottenere la sessione foreground corrente

```php theme={null}
use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

// Ottieni l'ID della sessione attualmente mostrata nel TUI
$sessionId = $client->getForegroundSessionId();

if ($sessionId !== null) {
    echo "Sessione foreground corrente: {$sessionId}";
}
```

### Impostare la sessione foreground

```php theme={null}
use Revolution\Copilot\Facades\Copilot;

$client = Copilot::client();

// Mostra nel TUI una sessione specifica
$client->setForegroundSessionId('session-123');
```

## ForegroundSessionInfo

Readonly class che contiene le informazioni della sessione foreground.

```php theme={null}
use Revolution\Copilot\Types\ForegroundSessionInfo;

readonly class ForegroundSessionInfo implements Arrayable
{
    public function __construct(
        public ?string $sessionId = null,      // ID sessione foreground
        public ?string $workspacePath = null,  // Percorso del workspace
    ) {}
}
```

## Uso in modalità TCP

Avviando Copilot CLI in modalità TUI+server e collegandoti dall'SDK, puoi sfruttare gli eventi del ciclo di vita.

```bash theme={null}
# Avvia Copilot CLI in modalità TUI+server
copilot --ui-server --port 8080
```

```php theme={null}
use Revolution\Copilot\Facades\Copilot;

// Connessione al server in modalità TCP
$client = Copilot::useTcp('tcp://127.0.0.1:8080')->client();

// Sottoscrivi gli eventi del ciclo di vita
$client->onLifecycle(function (SessionLifecycleEvent $event) {
    // Gestione dell'evento
});
```

## Note

* Gli eventi `session.foreground` e `session.background` si verificano solo in modalità TUI+server
* All'eliminazione della sessione (`session.deleted`) la proprietà `metadata` è `null`
* `onLifecycle()` restituisce una callback per annullare la sottoscrizione
* È una funzionalità distinta da `onSessionStart` e `onSessionEnd` di [Session Hooks](/it/packages/laravel-copilot-sdk/hooks)

<Info>
  Per le informazioni più recenti fai riferimento al [repository GitHub](https://github.com/invokable/laravel-copilot-sdk).
</Info>


## Related topics

- [Ciclo di vita della richiesta](/it/lifecycle.md)
- [Introduzione a Eloquent](/it/eloquent.md)
- [Hook di sessione](/it/packages/laravel-copilot-sdk/hooks.md)
- [GitHub Copilot SDK for Laravel](/it/packages/laravel-copilot-sdk/index.md)
- [Cast personalizzati di Eloquent](/it/advanced/eloquent-casts.md)