fle-php

name	fle-php
summary	Field-Level Encryption with the Couchbase PHP SDK — CryptoManager setup, encrypting and decrypting document fields
description	Field-Level Encryption with the Couchbase PHP SDK — CryptoManager setup, encrypting and decrypting document fields
compatibility	PHP SDK 4.x. couchbase/couchbase-encryption Composer package required.
metadata	{"last_verified":"2026-05","min_server_version":"6.0","handoff":[{"condition":"user asks about FLE concepts or supported SDKs","skill":"fle"},{"condition":"user asks about connection setup","skill":"server-connection-php"}]}

Field-Level Encryption — PHP

Setup

composer require couchbase/couchbase-encryption

Configure CryptoManager

use Couchbase\ClusterOptions;
use Couchbase\Cluster;
use CouchbaseEncryption\AeadAes256CbcHmacSha512Provider;
use CouchbaseEncryption\DefaultCryptoManager;
use CouchbaseEncryption\InsecureKeyring;

$keyBytes = str_repeat("\x00", 64); // 64-byte key for AES-256
$keyring = new InsecureKeyring(['my-key-id' => $keyBytes]);
$provider = new AeadAes256CbcHmacSha512Provider($keyring);

$cryptoManager = new DefaultCryptoManager();
$cryptoManager->registerEncrypter('my-encrypter', $provider->encrypterForKey('my-key-id'));
$cryptoManager->registerDecrypter($provider->decrypter());

$options = new ClusterOptions();
$options->credentials('username', 'Password!123');
$options->cryptoManager($cryptoManager);

$cluster = new Cluster('couchbase://localhost', $options);
$collection = $cluster->bucket('myapp')->defaultCollection();

Encrypting Fields on Write

$doc = [
    'name'        => 'Alice',
    'ssn'         => '123-45-6789',
    'credit_card' => '4111111111111111',
];

$upsertOptions = new \Couchbase\UpsertOptions();
$upsertOptions->encryptFields([
    'ssn'         => 'my-encrypter',
    'credit_card' => 'my-encrypter',
]);

$collection->upsert('user::alice', $doc, $upsertOptions);

Decrypting Fields on Read

$result = $collection->get('user::alice');
$doc = $result->content();
// Decryption is automatic when cryptoManager is configured
echo $doc['ssn']; // "123-45-6789"

Limitations

• Encrypted fields cannot be indexed or queried with SQL++
• Adds ~30% overhead to encrypted field size
• See fle for full concept reference