> 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/encryption/usage.md).

# Usage

For most application code, use the helpers.

## Encrypting and decrypting a value

```php
$user = [
    'id' => 15,
    'role' => 'admin',
];

$payload = crypto_encode($user);
$decoded = crypto_decode($payload);
```

With the default symmetric type, `crypto_decode($payload)` returns the original PHP value shape after decryption and unserialization.

## Choosing a cryptor type

```php
use Quantum\Encryption\Enums\CryptorType;

$token = crypto_encode('temporary', CryptorType::SYMMETRIC);
$value = crypto_decode($token, CryptorType::SYMMETRIC);
```

Asymmetric mode uses the same helper API:

```php
$token = crypto_encode('temporary', CryptorType::ASYMMETRIC);
$value = crypto_decode($token, CryptorType::ASYMMETRIC);
```

Use asymmetric mode only for short-lived, same-runtime flows. The generated keys are not persisted.

## Working with `CryptorFactory` directly

```php
use Quantum\Encryption\Factories\CryptorFactory;
use Quantum\Encryption\Enums\CryptorType;

$cryptor = CryptorFactory::get(CryptorType::SYMMETRIC);

$encrypted = $cryptor->encrypt('plain text');
$plain = $cryptor->decrypt($encrypted);
```

This bypasses the helper serialization layer. Here you are responsible for passing strings in and out.

## Inspecting the adapter

```php
$cryptor = CryptorFactory::get();

if ($cryptor->isAsymmetric()) {
    // runtime-specific key pair behavior applies
}
```

You can also inspect the concrete adapter with `getAdapter()` when debugging integration behavior.

## Recommended usage patterns

* use symmetric mode for values that must survive beyond one request or process
* ensure `app.key` is configured before using helper-driven packages such as Cookie or Session
* keep asymmetric payloads short; the built-in RSA adapter is not designed for large bodies or file-sized content
* use the raw `Cryptor` API only when you intentionally want string-in/string-out behavior without helper serialization

## Current limitations

* no API for custom ciphers or custom RSA settings
* no persisted public/private key management
* no authenticated payload metadata beyond what OpenSSL and the current wrapper format provide
* asymmetric encrypt/decrypt failures are not normalized into package exceptions once the adapter is constructed
* helper decoding does not preserve boolean `false` exactly


---

# 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/encryption/usage.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.