> For the complete documentation index, see [llms.txt](https://quantumphp.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantumphp.gitbook.io/docs/packages/session/contracts.md).

# Contracts

This page defines behavior you can rely on when integrating with Session.

## Wrapper contract

`session()` returns `Quantum\Session\Session`, which forwards supported calls to the active adapter.

The factory keeps one shared wrapper per adapter name for the current process, so repeated `session()` or `session('native')` calls reuse the same wrapper.

Unsupported method calls throw a session exception.

## Read/write contract

* `set(string $key, mixed $value): void`
* `get(string $key): mixed|null`
* `delete(string $key): void`
* `all(): array`

Session serializes and encrypts values on write, then decrypts and unserializes them on read. Scalars and arrays round-trip through the API, while backend storage keeps the encoded payload.

Use Session APIs as the source of truth for values.

## Presence contract

* `has(string $key): bool`

A key is considered present only when it exists and is not empty.

These values are treated as missing:

* `null`
* `false`
* `0`
* `'0'`
* `''`

Because `get()` depends on `has()`, these values read back as `null`.

## Flash contract

* `setFlash(string $key, mixed $value)`
* `getFlash(string $key): mixed|null`

`getFlash()` returns the value once and deletes it in the same call.

## Lifecycle contract

* `flush(): void` clears storage and destroys session state
* `getId(): ?string` returns current session ID when available
* `regenerateId(): bool` regenerates the ID for the active session, reopens the adapter, and keeps the same adapter config

Use `regenerateId()` after authentication or privilege changes.

## Adapter resolution contract

Supported adapter names:

* `native`
* `database`

Unknown adapter names raise a session exception during resolution.

When no adapter is passed, resolution uses `session.default` config.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://quantumphp.gitbook.io/docs/packages/session/contracts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.