Spatie Laravel Ciphersweet

https://github.com/spatie/laravel-ciphersweet
Admin
A Laravel package that integrates CipherSweet for searchable field-level encryption, allowing...
Tokens:10,658
Snippets:121
Trust Score:10
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Execute generate-key command

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/ConsoleCommands.md

Examples of running the command via the CLI with various options.

```bash
php artisan ciphersweet:generate-key
php artisan ciphersweet:generate-key --base64
php artisan ciphersweet:generate-key --show
```

--------------------------------

### Install package via Composer

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/README.md

Use this command to add the package to your Laravel project.

```bash
composer require spatie/laravel-ciphersweet
```

--------------------------------

### Run Encryption Command via CLI

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/ConsoleCommands.md

Examples of executing the encryption command from the terminal with different sort directions.

```bash
php artisan ciphersweet:encrypt App\\User <new-key>
php artisan ciphersweet:encrypt App\\User <new-key> desc
```

--------------------------------

### Implementing CipherSweetEncrypted

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/CipherSweetEncrypted.md

Example of a model implementing the interface and using the UsesCipherSweet trait to configure encrypted fields.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\LaravelCipherSweet\Contracts\CipherSweetEncrypted;
use Spatie\LaravelCipherSweet\Concerns\UsesCipherSweet;
use ParagonIE\CipherSweet\EncryptedRow;

class User extends Model implements CipherSweetEncrypted
{
    use UsesCipherSweet;

    public static function configureCipherSweet(EncryptedRow $encryptedRow): void
    {
        $encryptedRow->addField('email');
    }
}
```

--------------------------------

### Usage of whereBlind query scope

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Example of searching for a record using a blind index.

```php
$user = User::whereBlind('email', 'email_index', 'rias@spatie.be')->first();
```

--------------------------------

### Usage of orWhereBlind query scope

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Example of combining standard query conditions with blind index OR conditions.

```php
$user = User::where('active', true)
    ->whereBlind('email', 'email_index', 'a@b.com')
    ->orWhereBlind('phone', 'phone_index', '555-0100')
    ->first();
```

--------------------------------

### Publish and run migrations

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/README.md

Required steps to set up the necessary database tables for the package.

```bash
php artisan vendor:publish --tag="ciphersweet-migrations"
php artisan migrate
```

--------------------------------

### Implement handle method

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/ConsoleCommands.md

Logic for generating the key and updating the environment file or displaying the key.

```php
public function handle()
{
    $key = $this->generateRandomKey();

    if ($this->option('show')) {
        $this->line('<comment>' . $key . '</comment>');
        return;
    }

    if (! $this->setKeyInEnvironmentFile($key)) {
        return;
    }

    $this->laravel['config']['ciphersweet.providers.string.key'] = $key;
    $this->components->info('CipherSwift key set successfully.');
}
```

--------------------------------

### Handle Command Execution

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/ConsoleCommands.md

The main entry point for the command, validating input and initiating the encryption process.

```php
public function handle(): int
{
    if (! $this->ensureValidInput()) {
        return self::INVALID;
    }

    $modelClass = $this->argument('model');
    $this->encryptModelValues($modelClass);

    return self::SUCCESS;
}
```

--------------------------------

### Configuring the Package

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/LaravelCipherSweetServiceProvider.md

The configurePackage method registers package resources like the configuration file, migrations, and console commands.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name('laravel-ciphersweet')
        ->hasConfigFile()
        ->hasMigration('create_blind_indexes_table')
        ->hasCommands(GenerateKeyCommand::class, EncryptCommand::class);
}
```

--------------------------------

### Publish configuration file

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/README.md

Optional command to publish the package configuration file to your config directory.

```bash
php artisan vendor:publish --tag="ciphersweet-config"
```

--------------------------------

### Run package tests

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/README.md

Execute the test suite using Composer.

```bash
composer test
```

--------------------------------

### Configure Environment Variable

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/README.md

Add the generated key to the .env file for application use.

```text
CIPHERSWEET_KEY=<YOUR-KEY>
```

--------------------------------

### Implement Custom Backend

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/README.md

Define a custom backend by creating an invokable factory and implementing the BackendInterface.

```php
class CustomBackendFactory {
    public function __invoke()
    {
        return new CustomBackend();
    }
}

class CustomBackend implements BackendInterface {

    public function encrypt(string $plaintext, SymmetricKey $key, string $aad = ''): string
    {
        // Your logic here.
    }

    public function decrypt(string $ciphertext, SymmetricKey $key, string $aad = ''): string
    {
        // Your logic here.
    }

    public function blindIndexFast(string $plaintext, SymmetricKey $key, ?int $bitLength = null): string
    {
        // Your logic here.
    }

    public function blindIndexSlow(string $plaintext, SymmetricKey $key, ?int $bitLength = null, array $config = []): string
    {
        // Your logic here.
    }

    public function getIndexTypeColumn(string $tableName, string $fieldName, string $indexName): string
    {
        // Your logic here.
    }

    public function deriveKeyFromPassword(string $password, string $salt): SymmetricKey
    {
        // Your logic here.return new SymmetricKey('123');
    }

    public function doStreamDecrypt($inputFP, $outputFP, SymmetricKey $key, int $chunkSize = 8192, ?AAD $aad = null): bool
    {
        // Your logic here.
    }

    public function doStreamEncrypt($inputFP, $outputFP, SymmetricKey $key, int $chunkSize = 8192, string $salt = Constants::DUMMY_SALT, ?AAD $aad = null): bool
    {
        // Your logic here.
    }

    public function getFileEncryptionSaltOffset(): int
    {
        // Your logic here.
    }

    public function getPrefix(): string
    {
        // Your logic here.
    }
}
```

--------------------------------

### Implement a custom key provider

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/README.md

Create an invokable factory class that returns an implementation of KeyProviderInterface to use with the custom provider configuration.

```php
class CustomKeyProviderFactory {
    public function __invoke()
    {
        return new CustomKeyProvider();
    }
}

class CustomKeyProvider implements KeyProviderInterface {

    public function getSymmetricKey(): SymmetricKey
    {
        return new SymmetricKey(''); // Your logic here.
    }
}
```

--------------------------------

### Importing the Interface

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/CipherSweetEncrypted.md

The standard import path for the CipherSweetEncrypted interface.

```php
use Spatie\LaravelCipherSweet\Contracts\CipherSweetEncrypted;
```

--------------------------------

### Register Console Commands in Service Provider

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/ConsoleCommands.md

Use the hasCommands method within the package service provider to register the CipherSweet console commands.

```php
$package->hasCommands(GenerateKeyCommand::class, EncryptCommand::class);
```

--------------------------------

### Import ModelObserver

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/ModelObserver.md

Namespace import for the ModelObserver class.

```php
use Spatie\LaravelCipherSweet\Observers\ModelObserver;
```

--------------------------------

### Display Completion Information

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/ConsoleCommands.md

Outputs summary information to the console after the encryption process completes.

```php
$this->info("Updated {$updatedRows} rows.");
$this->info("You can now set your config key to the new key.");
```

--------------------------------

### Define Command Signature and Description

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/ConsoleCommands.md

Defines the console command signature and description within the EncryptCommand class.

```php
protected $signature = 'ciphersweet:encrypt {model} {newKey} {sortDirection=asc} {tablename?}';
protected $description = 'Encrypt the values of a model';
```

--------------------------------

### Define GenerateKeyCommand class

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/ConsoleCommands.md

The command class definition using the AsCommand attribute and signature string.

```php
#[AsCommand(name: 'ciphersweet:generate-key')]
class GenerateKeyCommand extends Command
{
    use ConfirmableTrait;

    protected $signature = 'ciphersweet:generate-key
        {--show : Display the CipherSwift key instead of modifying files}
        {--base64 : Generate key in base64 safe format}
        {--force : Force the operation to run when in production}';

    protected $description = 'Set the CipherSwift key';
}
```

--------------------------------

### Registering Package Bindings and Macros

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/LaravelCipherSweetServiceProvider.md

The packageRegistered method handles singleton binding for the CipherSweet engine and registers the encryptedUnique validation rule macro.

```php
public function packageRegistered()
{
    $this->app->singleton(CipherSweet::class, function () {
        $backend = $this->buildBackend();

        return new CipherSweet($this->buildKeyProvider($backend), $backend);
    });

    Rule::macro('encryptedUnique', function (string $model, string $indexName, ?string $column = null) {
        return new EncryptedUniqueRule($model, $indexName, $column);
    });
}
```

--------------------------------

### EncryptedUniqueRule Constructor

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/EncryptedUniqueRule.md

Initializes a new instance of the EncryptedUniqueRule.

```APIDOC
## Constructor

### Signature
`public function __construct(string $model, string $indexName, ?string $column = null)`

### Parameters
- **$model** (string) - Required - The Eloquent model class name to run the unique check against (must implement CipherSweetEncrypted).
- **$indexName** (string) - Required - The blind index name configured on the model.
- **$column** (?string) - Optional - The database column to query. If null, the validation attribute name is used.
```

--------------------------------

### Encrypt Model Attributes

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/README.md

Run the encryption command to process model fields and build blind indexes.

```bash
php artisan ciphersweet:encrypt <your-model-class> <generated-key>
```

--------------------------------

### CipherSweet configuration file contents

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/README.md

The default configuration file structure for defining the cryptographic backend and key provider settings.

```php
return [
    /*
     * This controls which cryptographic backend will be used by CipherSweet.
     * Unless you have specific compliance requirements, you should choose
     * "nacl".
     *
     * Supported: "boring", "fips", "nacl"
     */

    'backend' => env('CIPHERSWEET_BACKEND', 'nacl'),

    /*
     * Select which key provider your application will use. The default option
     * is to read a string literal out of .env, but it's also possible to
     * provide the key in a file or use random keys for testing.
     *
     * Supported: "file", "random", "string"
     */

    'provider' => env('CIPHERSWEET_PROVIDER', 'string'),

    /*
     * Set provider-specific options here. "string" will read the key directly
     * from your .env file. "file" will read the contents of the specified file
     * to use as your key. "custom" points to a factory class that returns a
     * provider from its `__invoke` method. Please see the docs for more details.
     */
    'providers' => [
        'file' => [
            'path' => env('CIPHERSWEET_FILE_PATH'),
        ],
        'string' => [
            'key' => env('CIPHERSWEET_KEY'),
        ],
    ],
    
    /*
     * The provided code snippet checks whether the $permitEmpty property is set to false
     * for a given field. If it is not set to false, it throws an EmptyFieldException indicating
     * that the field is not defined in the row. This ensures that the code enforces the requirement for
     * the field to have a value and alerts the user if it is empty or undefined.
     * Supported: "true", "false"
     */
    'permit_empty' => env('CIPHERSWEET_PERMIT_EMPTY', FALSE)

];
```

--------------------------------

### Import EncryptedUniqueRule

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/EncryptedUniqueRule.md

Required namespace import for utilizing the EncryptedUniqueRule validation rule.

```php
use Spatie\LaravelCipherSweet\Rules\EncryptedUniqueRule;
```

--------------------------------

### Generate CipherSweet Encryption Key

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/README.md

Use the artisan command to generate a new encryption key for the application.

```bash
php artisan ciphersweet:generate-key
```

--------------------------------

### Configure CipherSweet Fields and Indexes

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Defines the abstract method for registering encrypted fields and blind indexes on a model.

```php
abstract public static function configureCipherSweet(EncryptedRow $encryptedRow): void;
```

```php
use ParagonIE\CipherSweet\EncryptedRow;
use ParagonIE\CipherSweet\BlindIndex;

public static function configureCipherSweet(EncryptedRow $encryptedRow): void
{
    $encryptedRow
        ->addField('email')
        ->addOptionalTextField('name')
        ->addBlindIndex('email', new BlindIndex('email_index'));
}
```

--------------------------------

### ciphersweet:generate-key

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/ConsoleCommands.md

Generates a CipherSweet encryption key and writes it to the environment file or displays it in the console.

```APIDOC
## ciphersweet:generate-key

### Description
Generates a random CipherSweet encryption key. By default, it writes the key to the .env file as CIPHERSWEET_KEY. It supports options to display the key instead of saving it, use base64 encoding, or force execution in production.

### Usage
`php artisan ciphersweet:generate-key [options]`

### Options
- **--show** (flag) - Display the generated key instead of writing it to the environment file.
- **--base64** (flag) - Emit the key in base64 (URL-safe) encoding instead of hexadecimal.
- **--force** (flag) - Allow the operation to run in a production environment.

### Examples
```bash
php artisan ciphersweet:generate-key
php artisan ciphersweet:generate-key --base64
php artisan ciphersweet:generate-key --show
```
```

--------------------------------

### Resolving the CipherSweet Singleton

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/LaravelCipherSweetServiceProvider.md

The CipherSweet instance is available as a singleton, ensuring consistent configuration throughout the application.

```php
use ParagonIE\\(CipherSweet\\CipherSweet;

$engine = app(CipherSweet::class); // resolved, configured singleton
```

--------------------------------

### Boot UsesCipherSweet trait

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Registers Eloquent lifecycle event listeners that delegate model operations to the ModelObserver.

```php
protected static function bootUsesCipherSweet()
{
    static::$cipherSweetEncryptedRow = null;

    static::retrieved(function ($model) {
        app(ModelObserver::class)->retrieved($model);
    });
    static::saving(function ($model) {
        app(ModelObserver::class)->saving($model);
    });
    static::saved(function ($model) {
        app(ModelObserver::class)->saved($model);
    });
    static::deleting(function ($model) {
        app(ModelObserver::class)->deleting($model);
    });
}
```

--------------------------------

### Import the LaravelCipherSweetServiceProvider

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/LaravelCipherSweetServiceProvider.md

Use this statement to import the service provider class into your application code.

```php
use Spatie\LaravelCipherSweet\LaravelCipherSweetServiceProvider;
```

--------------------------------

### Configure CipherSweet on a Model

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/README.md

Implement the CipherSweetEncrypted interface and configure fields and blind indexes within the configureCipherSweet method.

```php
use Spatie\\\LaravelCipherSweet\\\Contracts\\\CipherSweetEncrypted;
use Spatie\\\LaravelCipherSweet\\\Concerns\\\UsesCipherSweet;
use ParagonIE\\\CipherSweet\\\EncryptedRow;
use ParagonIE\\\CipherSweet\\\BlindIndex;
use Illuminate\\\Database\\\Eloquent\\\Model;

class User extends Model implements CipherSweetEncrypted
{
    use UsesCipherSweet;
    
    /**
     * Encrypted Fields
     *
     * Each column that should be encrypted should be added below. Each column
     * in the migration should be a `text` type to store the encrypted value.
     *
     * ```
     * ->addField('column_name')
     * ->addBooleanField('column_name')
     * ->addIntegerField('column_name')
     * ->addTextField('column_name')
     * ```
     *
     * Optional Fields
     * 
     * These do not encrypt when NULL is provided as a value.
     * Instead, they become an unencrypted NULL.
     * 
     * ```
     * ->addOptionalTextField('column_name')
     * ->addOptionalBooleanField('column_name')
     * ->addOptionalFloatField('column_name')
     * ->addOptionalIntegerField('column_name')
     * ```
     * 
     * A JSON array can be encrypted as long as the key structure is defined in
     * a field map. See the docs for details on defining field maps.
     *
     * ```
     * ->addJsonField('column_name', $fieldMap)
     * ```
     *
     * Each field that should be searchable using an exact match needs to be
     * added as a blind index. Partial search is not supported. See the docs
     * for details on bit sizes and how to use compound indexes.
     *
     * ```
     * ->addBlindIndex('column_name', new BlindIndex('column_name_index'))
     * ```
     *
     * @see https://github.com/spatie/laravel-ciphersweet
     * @see https://ciphersweet.paragonie.com/
     * @see https://ciphersweet.paragonie.com/php/blind-index-planning
     * @see https://github.com/paragonie/ciphersweet/blob/master/src/EncryptedRow.php
     *
     * @param EncryptedRow $encryptedRow
     *
     * @return void
     */
    public static function configureCipherSweet(EncryptedRow $encryptedRow): void
    {
        $encryptedRow
            ->addField('email')
            ->addBlindIndex('email', new BlindIndex('email_index'));
    }
}
```

--------------------------------

### Validate using the Rule macro

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/EncryptedUniqueRule.md

Use the Rule::encryptedUnique macro registered by the service provider for cleaner syntax.

```php
use Illuminate\\Validation\\Rule;

$request->validate([
    'email' => [Rule::encryptedUnique(User::class, 'email_index')],
]);
```

--------------------------------

### Define EncryptedUniqueRule Constructor

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/EncryptedUniqueRule.md

The constructor initializes the model, blind index name, and optional database column for the uniqueness check.

```php
public function __construct(
    protected string  $model,
    protected string  $indexName,
    protected ?string $column = null
) {
}
```

--------------------------------

### Search Using Blind Indexes

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/README.md

Use the whereBlind scope to perform exact match searches on encrypted columns.

```php
$user = User::whereBlind('email', 'email_index', 'rias@spatie.be');
```

--------------------------------

### Registering the Service Provider in composer.json

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/LaravelCipherSweetServiceProvider.md

The provider is registered automatically via the extra.laravel.providers entry in the composer.json file.

```json
"providers": [
    "Spatie\LaravelCipherSweet\LaravelCipherSweetServiceProvider"
]
```

--------------------------------

### Handle model saved

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/ModelObserver.md

Invoked after persistence to restore plaintext in memory, reconcile changes, and update blind indexes.

```php
public function saved(CipherSweetEncrypted $model): void
{
    $model->decryptRow();

    $model->excludeNonChangedEncryptedAttributesFromChanges();

    $model->updateBlindIndexes();
}
```

--------------------------------

### Define saveDirtyAttributesForCipherSweet method

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Captures the current dirty attributes before encryption occurs.

```php
public function saveDirtyAttributesForCipherSweet(): self
{
    $this->cipherSweetSavingUnencryptedAttributes = $this->getDirty();

    return $this;
}
```

--------------------------------

### Trait Import Path

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

The namespace required to use the UsesCipherSweet trait in your Eloquent models.

```php
use Spatie\LaravelCipherSweet\Concerns\UsesCipherSweet;
```

--------------------------------

### Resolve Cryptographic Backend

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/LaravelCipherSweetServiceProvider.md

Resolves the BackendInterface implementation based on the ciphersweet.backend configuration value.

```php
protected function buildBackend(): BackendInterface
{
    if (config('ciphersweet.backend') === 'custom') {
        $class = config('ciphersweet.backends.custom');
        $backend = (new $class())();

        if (! $backend instanceof BackendInterface) {
            throw new \Exception($backend::class . ' must implement ' . BackendInterface::class);
        }

        return $backend;
    }

    return match (config('ciphersweet.backend')) {
        'fips' => new FIPSCrypto(),
        'boring' => new BoringCrypto(),
        default => new ModernCrypto(),
    };
}
```

--------------------------------

### Handle model saving

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/ModelObserver.md

Invoked before persistence to encrypt fields; note that encrypted values may appear in the dirty attribute list.

```php
public function saving(CipherSweetEncrypted $model): void
{
    $model->saveDirtyAttributesForCipherSweet();

    $model->encryptRow();

    // NOTE: If other listeners are called after this, all the encrypted attributes will appear in the dirty list
    // since each field will contain their encrypted value.
    // Having "Listener priority" might fix this (put the encrypter at the lowest priority
    // so all other listeners are called first), but Laravel doesn't support that (yet).
}
```

--------------------------------

### Define scopeOrWhereBlind method

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Adds an orWhereExists clause to allow OR conditions on blind indexes.

```php
public function scopeOrWhereBlind(
    Builder $query,
    string $column,
    string $indexName,
    string|array $value
): Builder {
    return $query->orWhereExists(fn (Builder $query): Builder => $this->buildBlindQuery($query, $column, $indexName, $value));
}
```

--------------------------------

### Resolve Key Provider

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/LaravelCipherSweetServiceProvider.md

Resolves the KeyProviderInterface implementation based on the ciphersweet.provider configuration value.

```php
protected function buildKeyProvider(BackendInterface $backend): KeyProviderInterface
{
    if (config('ciphersweet.provider') === 'custom') {
        $class = config('ciphersweet.providers.custom');
        $provider = (new $class())();

        if (! $provider instanceof KeyProviderInterface) {
            throw new \Exception($provider::class . ' must implement ' . KeyProviderInterface::class);
        }

        return $provider;
    }

    return match (config('ciphersweet.provider')) {
        'file' => new FileProvider(config('ciphersweet.providers.file.path')),
        'string' => new StringProvider(config('ciphersweet.providers.string.key')),
        default => new RandomProvider($backend),
    };
}
```

--------------------------------

### Define scopeWhereBlind method

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Adds a whereExists clause to the query builder to perform blind index matching.

```php
public function scopeWhereBlind(
    Builder $query,
    string $column,
    string $indexName,
    string|array $value
): Builder {
    return $query->whereExists(fn (Builder $query): Builder => $this->buildBlindQuery($query, $column, $indexName, $value));
}
```

--------------------------------

### scopeWhereBlind

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Adds a whereExists clause to a query to perform a blind index search on an encrypted column.

```APIDOC
## scopeWhereBlind(Builder $query, string $column, string $indexName, string|array $value)

### Description
Adds a `whereExists` clause delegating the matching to `buildBlindQuery()` to search encrypted data using a blind index.

### Parameters
- **$query** (Illuminate\Contracts\Database\Query\Builder) - Required - The Query builder injected by the scope resolver
- **$column** (string) - Required - The encrypted column to search on
- **$indexName** (string) - Required - The blind index name configured via `addBlindIndex()`
- **$value** (string|array) - Required - Plaintext value(s) to hash and match

### Usage
```php
$user = User::whereBlind('email', 'email_index', 'rias@spatie.be')->first();
```
```

--------------------------------

### Rotate Encryption Keys

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/README.md

Re-encrypt existing data by running the encryption command with a new key.

```bash
php artisan ciphersweet:encrypt "App\\User" <your-new-key>
```

--------------------------------

### Build Blind Query Method

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Constructs a subquery to filter records based on blind index values. This method is used internally to perform lookups on encrypted data.

```php
private function buildBlindQuery(
    Builder $query,
    string $column,
    string $indexName,
    string|array $value
): Builder {
    $prefix = $this->getConnection()->getTablePrefix();

    return $query->select(DB::raw(1))
        ->from('blind_indexes')
        ->where('indexable_type', $this->getMorphClass())
        ->where('indexable_id', DB::raw($prefix.$this->getTable() . '.' . $this->getKeyName()))
        ->where('name', $indexName)
        ->where('value', static::getCipherSweetEncryptedRow()->getBlindIndex($indexName, [$column => $value]));
}
```

--------------------------------

### encryptRow()

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Encrypts all encrypted fields on the model in place.

```APIDOC
## encryptRow()

### Description
Encrypts all encrypted fields on the model. Missing encrypted fields are defaulted to null before encryption.

### Return
- **void**

### Throws
- \ParagonIE\CipherSweet\Exception\ArrayKeyException
- \ParagonIE\CipherSweet\Exception\CryptoOperationException
- \SodiumException

### Usage
```php
$model->encryptRow();
$model->save();
```
```

--------------------------------

### Handle model deletion

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/ModelObserver.md

Invoked before a model is deleted to remove associated blind indexes.

```php
public function deleting(CipherSweetEncrypted $model): void
{
    $model->deleteBlindIndexes();
}
```

--------------------------------

### Handle model retrieval

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/ModelObserver.md

Invoked after a model is loaded to decrypt fields, silently swallowing EmptyFieldException if partial data is encountered.

```php
public function retrieved(CipherSweetEncrypted $model): void
{
    try {
        $model->decryptRow();
    } catch (EmptyFieldException) {
        // Not all fields are available to decrypt.
    }
}
```

--------------------------------

### Interface Definition

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/CipherSweetEncrypted.md

The core interface definition for CipherSweetEncrypted, outlining the required methods for models.

```php
use Illuminate\Contracts\Database\Query\Builder;
use ParagonIE\CipherSweet\EncryptedRow;

/** @mixin \Illuminate\Database\Eloquent\Model */
interface CipherSweetEncrypted
{
    public static function configureCipherSweet(EncryptedRow $encryptedRow): void;

    public function encryptRow(): void;

    public function decryptRow(): void;

    public function updateBlindIndexes(): void;

    public function deleteBlindIndexes(): void;

    public function scopeWhereBlind(
        Builder $query,
        string $column,
        string $indexName,
        string|array $value
    ): Builder;

    public function scopeOrWhereBlind(
        Builder $query,
        string $column,
        string $indexName,
        string|array $value
    ): Builder;
}
```

--------------------------------

### configureCipherSweet(EncryptedRow $encryptedRow)

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

An abstract method that must be implemented by concrete models to define encrypted fields and blind indexes.

```APIDOC
## configureCipherSweet(EncryptedRow $encryptedRow)

### Description
This abstract method serves as the registration point for encrypted fields and blind indexes on a per-model basis.

### Signature
`abstract public static function configureCipherSweet(EncryptedRow $encryptedRow): void`

### Parameters
- **$encryptedRow** (`EncryptedRow`) - Required - The row descriptor on which fields, types, field maps, and blind indexes are registered.

### Returns
- **void**
```

--------------------------------

### Encrypt model row

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Encrypts all encrypted fields on the model. Missing fields are defaulted to null before encryption.

```php
public function encryptRow(): void
{
    $fieldsToEncrypt = static::getCipherSweetEncryptedRow()->listEncryptedFields();

    $attributes = $this->getAttributes();

    foreach ($fieldsToEncrypt as $field) {
        $attributes[$field] ??= null;
    }

    $this->setRawAttributes(static::getCipherSweetEncryptedRow()->encryptRow($attributes));
}
```

```php
$model->encryptRow();
$model->save();
```

--------------------------------

### Update blind indexes

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Computes and writes all blind indexes for the model's current attributes using an upsert operation.

```php
public function updateBlindIndexes(): void
{
    foreach (static::getCipherSweetEncryptedRow()->getAllBlindIndexes($this->getAttributes()) as $name => $blindIndex) {
        DB::connection($this->getConnectionName())->table('blind_indexes')->upsert([
            'value' => $blindIndex,
            'indexable_type' => $this->getMorphClass(),
            'indexable_id' => $this->getKey(),
            'name' => $name,
        ], [
            'indexable_type',
            'indexable_id',
            'name',
        ]);
    }
}
```

```php
$user->updateBlindIndexes();
```

--------------------------------

### Retrieve EncryptedRow Descriptor

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Returns the cached EncryptedRow descriptor for the model, instantiating it via reflection if necessary.

```php
public static function getCipherSweetEncryptedRow(): EncryptedRow
{
    if (static::$cipherSweetEncryptedRow === null) {
        $model = (new \ReflectionClass(static::class))->newInstanceWithoutConstructor();

        static::$cipherSweetEncryptedRow = new EncryptedRow(
            app(CipherSweetEngine::class),
            $model->getTable()
        );

        static::configureCipherSweet(static::$cipherSweetEncryptedRow);
    }

    return static::$cipherSweetEncryptedRow;
}
```

```php
$row = User::getCipherSweetEncryptedRow();
$fields = $row->listEncryptedFields();
```

--------------------------------

### scopeOrWhereBlind

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Adds an orWhereExists clause to a query to perform a blind index search on an encrypted column.

```APIDOC
## scopeOrWhereBlind(Builder $query, string $column, string $indexName, string|array $value)

### Description
Adds an `orWhereExists` clause so a blind-index condition can be OR'd into an existing query.

### Parameters
- **$query** (Builder) - Required - The query builder
- **$column** (string) - Required - Encrypted column
- **$indexName** (string) - Required - Blind index name
- **$value** (string|array) - Required - Plaintext value(s) to hash

### Usage
```php
$user = User::where('active', true)
    ->whereBlind('email', 'email_index', 'a@b.com')
    ->orWhereBlind('phone', 'phone_index', '555-0100')
    ->first();
```
```

--------------------------------

### Usage of saveDirtyAttributesForCipherSweet

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Invokes the method to record dirty attributes before the encryption process.

```php
$model->saveDirtyAttributesForCipherSweet();
```

--------------------------------

### Validate Encrypted Uniqueness

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/README.md

Use EncryptedUniqueRule or the Rule macro to validate uniqueness on encrypted fields via blind indexes.

```php
use Spatie\LaravelCipherSweet\Rules\EncryptedUniqueRule;

$request->validate([
    'email' => [new EncryptedUniqueRule(User::class, 'email_index')],
]);
```

```php
use Illuminate\Validation\Rule;

$request->validate([
    'email' => [Rule::encryptedUnique(User::class, 'email_index')],
]);
```

--------------------------------

### Validate model implementation of CipherSweetEncrypted

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/EncryptedUniqueRule.md

Internal method to ensure the provided model implements the required contract.

```php
/**
 * @throws RuntimeException
 */
private function checkModelHasEncryptedColumn(): void
{
    if (! is_subclass_of($this->model, CipherSweetEncrypted::class)) {
        throw new RuntimeException("The model {$this->model} must implement " . CipherSweetEncrypted::class);
    }
}
```

--------------------------------

### validate

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/EncryptedUniqueRule.md

Validates the uniqueness of the attribute value against the configured blind index.

```APIDOC
## validate(string $attribute, mixed $value, Closure $fail): void

### Description
Implements the ValidationRule contract to perform the uniqueness check.

### Parameters
- **$attribute** (string) - The attribute/field being validated.
- **$value** (mixed) - The value to test for uniqueness.
- **$fail** (Closure) - The callback invoked to report a validation failure.

### Throws
- **RuntimeException** - If the model does not implement CipherSweetEncrypted.
```

--------------------------------

### updateBlindIndexes()

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Computes and writes all blind indexes for the model's current attributes to the database.

```APIDOC
## updateBlindIndexes()

### Description
Computes and writes all blind indexes for the model's current attributes. It performs an upsert operation into the blind_indexes table.

### Return
- **void**

### Usage
```php
$user->updateBlindIndexes();
```
```

--------------------------------

### Usage of excludeNonChangedEncryptedAttributesFromChanges

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Invokes the cleanup method to ensure model changes reflect actual data updates.

```php
$model->excludeNonChangedEncryptedAttributesFromChanges();
```

--------------------------------

### Instantiate EncryptedUniqueRule in validation array

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/EncryptedUniqueRule.md

Directly use the rule within a standard Laravel validation array.

```php
use Spatie\\LaravelCipherSweet\\Rules\\EncryptedUniqueRule;

$request->validate([
    'email' => ['required', new EncryptedUniqueRule(User::class, 'email_index')],
]);
```

--------------------------------

### Declare UsesCipherSweet properties

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Properties used by the trait to manage the encrypted row descriptor and track dirty attributes during the saving process.

```php
public static ?EncryptedRow $cipherSweetEncryptedRow = null;
protected array $cipherSweetSavingUnencryptedAttributes = [];
```

--------------------------------

### saveDirtyAttributesForCipherSweet

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Records the model's dirty attribute set before encryption runs.

```APIDOC
## saveDirtyAttributesForCipherSweet()

### Description
Records the model's dirty attribute set before encryption runs to allow for accurate change tracking.

### Usage
```php
$model->saveDirtyAttributesForCipherSweet();
```
```

--------------------------------

### Delete blind indexes

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Removes all blind indexes recorded for the model from the database.

```php
public function deleteBlindIndexes(): void
{
    DB::connection($this->getConnectionName())->table('blind_indexes')
        ->where('indexable_type', $this->getMorphClass())
        ->where('indexable_id', $this->getKey())
        ->delete();
}
```

```php
$model->deleteBlindIndexes();
```

--------------------------------

### Define excludeNonChangedEncryptedAttributesFromChanges method

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Filters the model's changes map to prevent false-positives on encrypted fields that haven't actually changed.

```php
public function excludeNonChangedEncryptedAttributesFromChanges(): self
{
    $changes = $this->getChanges();

    if (! empty($changes)) {
        foreach (static::getCipherSweetEncryptedRow()->listEncryptedFields() as $field) {
            if (! array_key_exists($field, $this->cipherSweetSavingUnencryptedAttributes)) {
                unset($changes[$field]);
            } else {
                $changes[$field] = $this->cipherSweetSavingUnencryptedAttributes[$field];
            }
        }

        $this->changes = $changes;
    }

    $this->cipherSweetSavingUnencryptedAttributes = [];

    return $this;
}
```

--------------------------------

### Decrypt model row

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Decrypts the model's current attributes in place, respecting the ciphersweet.permit_empty configuration.

```php
public function decryptRow(): void
{
    $this->setRawAttributes(static::getCipherSweetEncryptedRow()->setPermitEmpty(config('ciphersweet.permit_empty', false))
        ->decryptRow($this->getAttributes()), true);
}
```

```php
try {
    $model->decryptRow();
} catch (EmptyFieldException) {
    // optional fields were missing
}
```

--------------------------------

### decryptRow()

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Decrypts the model's current attributes in place.

```APIDOC
## decryptRow()

### Description
Decrypts the model's current attributes in place. It respects the ciphersweet.permit_empty configuration setting.

### Return
- **void**

### Throws
- \ParagonIE\CipherSweet\Exception\EmptyFieldException

### Usage
```php
try {
    $model->decryptRow();
} catch (EmptyFieldException) {
    // optional fields were missing
}
```
```

--------------------------------

### getCipherSweetEncryptedRow()

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Retrieves the CipherSweet EncryptedRow descriptor for the model, caching it for subsequent calls.

```APIDOC
## getCipherSweetEncryptedRow()

### Description
Returns the CipherSweet `EncryptedRow` descriptor for the calling model. It builds and caches the descriptor on the first access.

### Signature
`public static function getCipherSweetEncryptedRow(): EncryptedRow`

### Returns
- **EncryptedRow** (`ParagonIE\CipherSweet\EncryptedRow`) - The row descriptor bound to the model's table.
```

--------------------------------

### ignoreModel

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/EncryptedUniqueRule.md

Configures the rule to ignore a specific model instance during the uniqueness check.

```APIDOC
## ignoreModel(Model $model, ?string $idColumn = null): static

### Parameters
- **$model** (Illuminate\Database\Eloquent\Model) - The model to ignore.
- **$idColumn** (?string) - Optional - Overrides the ID column; defaults to the model's getKeyName().

### Returns
- **static** - Returns the rule instance for method chaining.
```

--------------------------------

### Validate Encrypted Field Uniqueness

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/EncryptedUniqueRule.md

The validate method checks if the provided value exists in the database using the model's blind index scope.

```php
public function validate(string $attribute, mixed $value, Closure $fail): void
{
    $this->column ??= $attribute;

    $this->checkModelHasEncryptedColumn();

    $count = $this->model::whereBlind(
        $this->column,
        $this->indexName,
        $value
    )
        ->when($this->ignore, function ($query) {
            $query->whereNot($this->idColumn, $this->ignore);
        })
        ->count();

    if ($count) {
        $fail('validation.unique')->translate();
    }
}
```

--------------------------------

### Ignore Model Instance

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/EncryptedUniqueRule.md

The ignoreModel method excludes a specific Eloquent model instance from the uniqueness check.

```php
public function ignoreModel(Model $model, ?string $idColumn = null): static
{
    $this->idColumn = $idColumn ?? $model->getKeyName();
    $this->ignore = $model->{$this->idColumn};

    return $this;
}
```

```php
$rule->ignoreModel($user);
```

--------------------------------

### Ignore Record by ID

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/EncryptedUniqueRule.md

The ignore method excludes a specific record from the uniqueness check by its primary key.

```php
public function ignore(mixed $id, ?string $idColumn = null): static
{
    if ($id instanceof Model) {
        return $this->ignoreModel($id, $idColumn);
    }

    $this->ignore = $id;
    $this->idColumn = $idColumn ?? 'id';

    return $this;
}
```

```php
$rule->ignore($user->id);
```

--------------------------------

### EncryptedUniqueRule

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/EncryptedUniqueRule.md

The EncryptedUniqueRule class is used to validate that a value is unique within an encrypted column. It requires the model class and the blind index column name.

```APIDOC
## EncryptedUniqueRule

### Description
Validates that a given attribute is unique within an encrypted database column using a blind index.

### Constructor
`new EncryptedUniqueRule(string $model, string $column = null)`

- **$model** (string) - Required - The FQCN of the model to check.
- **$column** (string) - Optional - The name of the blind index column. Defaults to the attribute name if null.

### Methods
#### ignore(mixed $id)
- **$id** (mixed) - Required - The ID of the record to ignore during the uniqueness check.

### Usage Example
```php
use Spatie\LaravelCipherSweet\Rules\EncryptedUniqueRule;
use Illuminate\Validation\Rule;

// Direct instantiation
$request->validate([
    'email' => ['required', new EncryptedUniqueRule(User::class, 'email_index')],
]);

// Using the Rule macro
$request->validate([
    'email' => [Rule::encryptedUnique(User::class, 'email_index')],
]);

// Ignoring a record
$rule = new EncryptedUniqueRule(User::class, 'email_index');
$rule->ignore($user->id);
```
```

--------------------------------

### Ignore a record during validation

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/EncryptedUniqueRule.md

Use the ignore method to exclude a specific record ID from the uniqueness check.

```php
$rule = new EncryptedUniqueRule(User::class, 'email_index');
$rule->ignore($user->id);

$validator = validator(['email' => 'rias@spatie.be'], ['email' => $rule]);
```

--------------------------------

### ignore

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/EncryptedUniqueRule.md

Configures the rule to ignore a specific record ID during the uniqueness check.

```APIDOC
## ignore(mixed $id, ?string $idColumn = null): static

### Parameters
- **$id** (mixed) - The ID or an Illuminate\Database\Eloquent\Model instance to ignore.
- **$idColumn** (?string) - Optional - The ID column name; defaults to 'id' when $id is not a Model.

### Returns
- **static** - Returns the rule instance for method chaining.
```

--------------------------------

### deleteBlindIndexes()

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Removes all blind indexes recorded for the model from the database.

```APIDOC
## deleteBlindIndexes()

### Description
Removes all blind indexes recorded for the model by deleting rows from the blind_indexes table matching the model's morph class and primary key.

### Return
- **void**

### Usage
```php
$model->deleteBlindIndexes();
```
```

--------------------------------

### excludeNonChangedEncryptedAttributesFromChanges

Source: https://github.com/spatie/laravel-ciphersweet/blob/main/_autodocs/api-reference/UsesCipherSweet.md

Removes encrypted fields from the model's changes map unless they were dirty at save time.

```APIDOC
## excludeNonChangedEncryptedAttributesFromChanges()

### Description
Corrects false-diffs by removing non-dirty encrypted fields from the model's changes map and restoring real values for dirty ones.

### Usage
```php
$model->excludeNonChangedEncryptedAttributesFromChanges();
```
```
Tokens:
Raw