PHPackages                             tigusigalpa/yandex-lockbox-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. tigusigalpa/yandex-lockbox-php

ActiveLibrary[API Development](/categories/api)

tigusigalpa/yandex-lockbox-php
==============================

PHP/Laravel client library for Yandex Lockbox (secrets storage) API.

v2.0.1(5mo ago)41MITPHPPHP >=8.0CI passing

Since Nov 7Pushed 5mo agoCompare

[ Source](https://github.com/tigusigalpa/yandex-lockbox-php)[ Packagist](https://packagist.org/packages/tigusigalpa/yandex-lockbox-php)[ Docs](https://github.com/tigusigalpa/yandex-lockbox-php)[ RSS](/packages/tigusigalpa-yandex-lockbox-php/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (6)Versions (3)Used By (0)

Yandex Lockbox PHP SDK
======================

[](#yandex-lockbox-php-sdk)

[![Yandex Lockbox PHP SDK](https://private-user-images.githubusercontent.com/2721390/511316957-96588cc3-f6b7-4aa8-be93-c7c14e14bf38.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzU0MjMyNTgsIm5iZiI6MTc3NTQyMjk1OCwicGF0aCI6Ii8yNzIxMzkwLzUxMTMxNjk1Ny05NjU4OGNjMy1mNmI3LTRhYTgtYmU5My1jN2MxNGUxNGJmMzgucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDQwNSUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjA0MDVUMjEwMjM4WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ODkzM2Y2ZGJiM2IzYWM2MjI1MGE2YzZjODBkYzFiNDlkZGJkNjU0NTc1MDY2Y2JiYjE3ZDZlNTUxNDI0OWE0NiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.PcmQ_aceRQh1AdyllXbShWmI9MzT1FHIMM1xLZ_4xSY)](https://private-user-images.githubusercontent.com/2721390/511316957-96588cc3-f6b7-4aa8-be93-c7c14e14bf38.png?jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NzU0MjMyNTgsIm5iZiI6MTc3NTQyMjk1OCwicGF0aCI6Ii8yNzIxMzkwLzUxMTMxNjk1Ny05NjU4OGNjMy1mNmI3LTRhYTgtYmU5My1jN2MxNGUxNGJmMzgucG5nP1gtQW16LUFsZ29yaXRobT1BV1M0LUhNQUMtU0hBMjU2JlgtQW16LUNyZWRlbnRpYWw9QUtJQVZDT0RZTFNBNTNQUUs0WkElMkYyMDI2MDQwNSUyRnVzLWVhc3QtMSUyRnMzJTJGYXdzNF9yZXF1ZXN0JlgtQW16LURhdGU9MjAyNjA0MDVUMjEwMjM4WiZYLUFtei1FeHBpcmVzPTMwMCZYLUFtei1TaWduYXR1cmU9ODkzM2Y2ZGJiM2IzYWM2MjI1MGE2YzZjODBkYzFiNDlkZGJkNjU0NTc1MDY2Y2JiYjE3ZDZlNTUxNDI0OWE0NiZYLUFtei1TaWduZWRIZWFkZXJzPWhvc3QifQ.PcmQ_aceRQh1AdyllXbShWmI9MzT1FHIMM1xLZ_4xSY)

> 🇷🇺 [Русская версия документации](README-ru.md)

[![Latest Version](https://camo.githubusercontent.com/816449416f19c4634c6318cc838f9c7e4c77511c8a67feffa5ae61779b704bde/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f74696775736967616c70612f79616e6465782d6c6f636b626f782d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tigusigalpa/yandex-lockbox-php)[![PHP Version](https://camo.githubusercontent.com/7a69d7c320a5b8a36de96c93974bb86f261edb8d072ed5a845eb0db0cb5743ae/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f74696775736967616c70612f79616e6465782d6c6f636b626f782d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tigusigalpa/yandex-lockbox-php)[![License](https://camo.githubusercontent.com/1d8b416544a51949ed368d3b87d8ac2ac44016e8797d3c21391768eab9fb6920/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f74696775736967616c70612f79616e6465782d6c6f636b626f782d7068702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tigusigalpa/yandex-lockbox-php)[![Tests](https://camo.githubusercontent.com/f95554197fce7937f5b132382625226d5259a00a8e8ce521aba7137a250e403d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f74696775736967616c70612f79616e6465782d6c6f636b626f782d7068702f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/tigusigalpa/yandex-lockbox-php/actions)

PHP/Laravel client library for **Yandex Lockbox** — a secure secrets storage service in Yandex Cloud.

> **Note:** This package uses [yandex-cloud-client-php](https://github.com/tigusigalpa/yandex-cloud-client-php) for Yandex Cloud infrastructure management (authentication, organizations, clouds, folders).

📚 Documentation
---------------

[](#-documentation)

- [Yandex Lockbox Docs](https://yandex.cloud/en/docs/lockbox/)
- [Quickstart Guide](https://yandex.cloud/en/docs/lockbox/quickstart)
- [API Reference](https://yandex.cloud/en/docs/lockbox/api-ref/Secret/)
- [OAuth Token Guide](https://yandex.cloud/en/docs/iam/concepts/authorization/oauth-token)
- API Endpoint: `https://lockbox.api.cloud.yandex.net/lockbox/v1`

✨ Features
----------

[](#-features)

- ✅ Full Yandex Lockbox API support
- ✅ **Automatic IAM token generation from OAuth token**
- ✅ **Cloud infrastructure management** via yandex-cloud-client-php
- ✅ **Async operation handling** (wait for operations to complete)
- ✅ **Folder permissions management** (list/assign access bindings)
- ✅ PHP 8.0+ with strict types
- ✅ Laravel 8-12 integration (service provider, facade, config)
- ✅ Extensible token provider interface
- ✅ Typed exceptions for better error handling
- ✅ PSR-3 logger support
- ✅ Comprehensive test coverage

📦 Installation
--------------

[](#-installation)

```
composer require tigusigalpa/yandex-lockbox-php
```

### Development (path repository)

[](#development-path-repository)

For mono-repo development, add to your root `composer.json`:

```
{
    "repositories": [
        {
            "type": "path",
            "url": "public_html/packages/yandex-lockbox-php"
        }
    ],
    "require": {
        "tigusigalpa/yandex-lockbox-php": "*"
    }
}
```

Then run:

```
composer update tigusigalpa/yandex-lockbox-php
```

⚙️ Configuration (Laravel)
--------------------------

[](#️-configuration-laravel)

Publish the configuration file:

```
php artisan vendor:publish --tag=yandex-lockbox-config
```

Add environment variables to your `.env`:

```
# RECOMMENDED: Use OAuth token (starts with y0_, y1_, y2_, y3_)
# OAuth tokens don't expire and are automatically converted to IAM tokens
YANDEX_LOCKBOX_TOKEN=y0_your-oauth-token

# ALTERNATIVE: Use IAM token (starts with t1.)
# IAM tokens expire after 12 hours
# YANDEX_LOCKBOX_TOKEN=t1.your-iam-token

YANDEX_LOCKBOX_BASE_URI=https://lockbox.api.cloud.yandex.net/lockbox/v1
YANDEX_LOCKBOX_FOLDER_ID=your-default-folder-id
```

🔐 Authorization & API Connection Guide
------------------------------------------

[](#-authorization--api-connection-guide)

### Step 1: Getting OAuth Token

[](#step-1-getting-oauth-token)

**Documentation:** [OAuth Token Guide](https://yandex.cloud/en/docs/iam/concepts/authorization/oauth-token)

**Get token via OAuth request:**

```
https://oauth.yandex.com/authorize?response_type=token&client_id=1a6990aa636648e9b2ef855fa7bec2fb

```

1. Open the URL above in your browser
2. Authorize the application
3. Copy the OAuth token from the response URL (format: `y0_...`, `y1_...`, `y2_...`, `y3_...`)
4. Add token to `.env` (Laravel): ```
    YANDEX_LOCKBOX_TOKEN=y0_your-oauth-token
    ```

**Or pass directly to OAuthTokenProvider:**

```
use Tigusigalpa\YandexLockbox\Token\OAuthTokenProvider;

$tokenProvider = new OAuthTokenProvider('y0_your-oauth-token');
```

### Step 2: Getting IAM Token (Optional)

[](#step-2-getting-iam-token-optional)

**Documentation:** [How to get IAM token](https://yandex.cloud/en/docs/iam/operations/iam-token/create#exchange-token)

IAM token is generated automatically from OAuth token. But you can get it manually:

```
$tokenProvider = new OAuthTokenProvider('y0_your-oauth-token');

// Get IAM token (cached for 12 hours)
$iamToken = $tokenProvider->getToken();
```

**Alternative - using Yandex CLI:**

```
yc iam create-token
```

⚠️ Note: IAM tokens expire after 12 hours

### Step 3: Getting Cloud ID

[](#step-3-getting-cloud-id)

**Documentation:** [Retrieves the list of Cloud resources](https://yandex.cloud/en/docs/resource-manager/api-ref/Cloud/list)

**List all clouds:**

```
$tokenProvider = new OAuthTokenProvider('y0_your-oauth-token');

// Get cloud client for infrastructure management
$cloudClient = $tokenProvider->getCloudClient();

// Get all clouds
$clouds = $cloudClient->clouds()->list();

foreach ($clouds['clouds'] as $cloud) {
    echo "Cloud: {$cloud['name']} (ID: {$cloud['id']})\n";
}

// Use first cloud
$cloudId = $clouds['clouds'][0]['id'];
```

**Or get first cloud directly:**

```
// Get first cloud ID (convenience method)
$cloudId = $tokenProvider->getFirstCloudId();
```

### Step 4: Getting Folder ID

[](#step-4-getting-folder-id)

**Documentation:** [Retrieves the list of Folder resources in the specified cloud](https://yandex.cloud/en/docs/resource-manager/api-ref/Folder/list)

**List all folders in cloud:**

```
// Get all folders in cloud
$cloudClient = $tokenProvider->getCloudClient();
$folders = $cloudClient->folders()->list($cloudId);

foreach ($folders['folders'] as $folder) {
    echo "Folder: {$folder['name']} (ID: {$folder['id']})\n";
}

// Use first folder
$folderId = $folders['folders'][0]['id'];
```

**Or get first folder directly:**

```
// Get first folder ID (convenience method)
$folderId = $tokenProvider->getFirstFolderId($cloudId);

// Or get first folder from first cloud in one call
$folderId = $tokenProvider->getFirstFolderIdFromFirstCloud();
```

### Step 5: Add permissions to a folder

[](#step-5-add-permissions-to-a-folder)

**Documentation:** [Access management in Yandex Lockbox](https://yandex.cloud/en/docs/lockbox/security/)

> **You need to get Subject ID (user account ID that you want to assign permissions to) first**

\*\*Documentation: \*\* [Subjects that roles are assigned to](https://yandex.cloud/en/docs/iam/concepts/access-control/#subject)

\*\*Documentation: \*\* [Retrieves the list of Yandex Passport user accounts](https://yandex.cloud/en/docs/iam/api-ref/YandexPassportUserAccount/getByLogin)

```
$subjectId = $manager->getUserIdByLogin('your-yandex-login'); // your-yandex-login@yandex.ru
```

**Documentation:** [lockbox.editor](https://yandex.cloud/en/docs/lockbox/security/#lockbox-editor)

\*\*Documentation: \*\* [Setting up folder access permissions](https://yandex.cloud/en/docs/resource-manager/operations/folder/set-access-bindings)

```
$manager->assignRoleToFolder(
    $iamToken,
    $folderId,
    $subjectId,
    'lockbox.editor',
    'userAccount',
    true  // waitForCompletion - waits until operation is done
);
```

### Step 6: Working with Yandex Lockbox API

[](#step-6-working-with-yandex-lockbox-api)

**Documentation:** [Lockbox API, REST: Secret](https://yandex.cloud/en/docs/lockbox/api-ref/Secret/)

Now you can use the folder ID to work with secrets:

```
use Tigusigalpa\YandexLockbox\Client;
use Tigusigalpa\YandexLockbox\Token\OAuthTokenProvider;

// Create client with OAuth token
$tokenProvider = new OAuthTokenProvider('y0_your-oauth-token');
$client = new Client($tokenProvider);

// List all secrets in a folder
$secrets = $client->listSecrets($folderId);
foreach ($secrets['secrets'] as $secret) {
    echo "{$secret['name']} (ID: {$secret['id']})\n";
    echo "Description: {$secret['description']}\n";
    echo "Labels: " . json_encode($secret['labels']) . "\n";
    echo "Status: {$secret['status']}\n";
    echo "Created at: {$secret['createdAt']}\n";
    echo "Updated at: {$secret['updatedAt']}\n";
    echo "Current version: {$secret['currentVersion']}\n";
}

// Get secret metadata
// @see https://yandex.cloud/en/docs/lockbox/api-ref/Secret/get
$secret = $client->getSecret('your-secret-id');

// Get secret payload (actual values)
$payload = $client->getPayload('your-secret-id');
foreach ($payload['entries'] as $entry) {
    echo "{$entry['key']}: {$entry['textValue']}\n"; // or {$entry['binaryValue']}
}
echo $payload['versionId'];

// Optional: get specific version
$payload = $client->getPayload('your-secret-id', 'version-id');

// Create a new secret
// @see https://yandex.cloud/en/docs/lockbox/api-ref/Secret/create
$created = $client->createSecret([
    'folderId' => $folderId,
    'name' => 'my-api-keys',
    'description' => 'Production API keys',
    'labels' => ['env' => 'production'],
]);

$secretId = $created['id'];

// Add a new version with secret values
// Uses POST /secrets/{id}:addVersion endpoint
// @see https://yandex.cloud/en/docs/lockbox/api-ref/Secret/addVersion
$version = $client->addVersion($secretId, [
    'description' => 'Version with API keys',  // Optional
    'payloadEntries' => [
        ['key' => 'API_KEY', 'textValue' => 'super-secret-key'],
        ['key' => 'API_SECRET', 'textValue' => 'super-secret-value'],
    ],
]);

// Update secret metadata
$updated = $client->updateSecret($secretId, [
    'name' => 'updated-name',
    'description' => 'Updated description',
]);

// List all versions
$versions = $client->listVersions($secretId);

// Activate/Deactivate secret
$client->activateSecret($secretId);
$client->deactivateSecret($secretId);

// Schedule version destruction (7 days by default)
$client->scheduleVersionDestruction($secretId, 'version-id', '604800s');

// Cancel scheduled destruction
$client->cancelVersionDestruction($secretId, 'version-id');

// Delete secret
$client->deleteSecret($secretId);

// List operations
$operations = $client->listOperations($secretId);

// Access control
$bindings = $client->listAccessBindings($secretId);
$client->setAccessBindings($secretId, [
    ['roleId' => 'viewer', 'subject' => ['type' => 'userAccount', 'id' => 'user-id']],
]);
```

### Handling Asynchronous Operations

[](#handling-asynchronous-operations)

Some Yandex Cloud operations (like `assignRoleToFolder`) are asynchronous and return an operation object with `done=false`. You have two options:

**Option 1: Wait for completion automatically**

```
$manager = new OAuthTokenManager('y0_your-oauth-token');
$iamToken = $manager->getIamToken();

// Set waitForCompletion to true (6th parameter)
$result = $manager->assignRoleToFolder(
    $iamToken,
    'folder-id',
    'user-id',
    'lockbox.editor',
    'userAccount',
    true,  // waitForCompletion
    60     // maxWaitSeconds (optional, default: 60)
);

// $result['done'] will be true
```

**Option 2: Poll operation status manually**

```
// Start operation
$operation = $manager->assignRoleToFolder($iamToken, 'folder-id', 'user-id', 'lockbox.editor');

// Check if done
if (!$operation['done']) {
    // Wait for operation to complete
    $completed = $manager->waitForOperation(
        $iamToken,
        $operation['id'],
        60  // maxWaitSeconds (optional)
    );

    if ($completed['done']) {
        echo "Operation completed successfully!\n";
    }
}

// Or check status without waiting
$status = $manager->getOperation($iamToken, $operation['id']);
echo "Operation status: " . ($status['done'] ? 'completed' : 'in progress') . "\n";
```

### Managing Folder Permissions

[](#managing-folder-permissions)

List and manage access bindings (permissions) for folders:

```
use Tigusigalpa\YandexLockbox\Auth\OAuthTokenManager;

$manager = new OAuthTokenManager('y0_your-oauth-token');
$iamToken = $manager->getIamToken();

// List access bindings with pagination
$result = $manager->listFolderAccessBindings($iamToken, 'folder-id', 100);
foreach ($result['accessBindings'] as $binding) {
    echo "Role: {$binding['roleId']}\n";
    echo "Subject: {$binding['subject']['id']} ({$binding['subject']['type']})\n";
}

// Handle pagination if needed
if (isset($result['nextPageToken'])) {
    $nextPage = $manager->listFolderAccessBindings(
        $iamToken,
        'folder-id',
        100,
        $result['nextPageToken']
    );
}

// Get all bindings at once (automatic pagination)
$allBindings = $manager->getAllFolderAccessBindings($iamToken, 'folder-id');
echo "Total permissions: " . count($allBindings) . "\n";

// Group by role
$byRole = [];
foreach ($allBindings as $binding) {
    $byRole[$binding['roleId']][] = $binding['subject'];
}
```

**Response structure:**

```
[
    'accessBindings' => [
        [
            'roleId' => 'lockbox.editor',  // Role identifier
            'subject' => [
                'id' => 'ajef55nu903fiklhapf9',  // User/SA ID
                'type' => 'userAccount'  // 'userAccount' or 'serviceAccount'
            ]
        ],
        // ... more bindings
    ],
    'nextPageToken' => 'token...'  // Present if more pages available
]
```

### Laravel Facade

[](#laravel-facade)

```
use Tigusigalpa\YandexLockbox\Laravel\Facades\Lockbox;

// List secrets using default folder from config
$secrets = Lockbox::listSecrets(config('lockbox.default_folder_id'));

// Get secret metadata
$secret = Lockbox::getSecret('secret-id');

// Get actual secret values
$payload = Lockbox::getPayload('secret-id');
foreach ($payload['entries'] as $entry) {
    echo $entry['key'] . ': ' . $entry['textValue'] . PHP_EOL;
}

// Create secret
$created = Lockbox::createSecret([
    'folderId' => config('lockbox.default_folder_id'),
    'name' => 'laravel-secrets',
    'description' => 'Laravel application secrets',
]);

// Add version
$version = Lockbox::addVersion('secret-id', [
    'payloadEntries' => [
        ['key' => 'DB_PASSWORD', 'textValue' => env('DB_PASSWORD')],
        ['key' => 'APP_KEY', 'textValue' => env('APP_KEY')],
    ],
]);
```

### Laravel Artisan Commands

[](#laravel-artisan-commands)

```
# Test connection
php artisan lockbox:test

# List all secrets
php artisan lockbox:list

# Show secret details
php artisan lockbox:show  --payload

# Create new secret
php artisan lockbox:create my-secret --description="My secret"

# Add version with values
php artisan lockbox:add-version  \
  --entry=KEY1=value1 \
  --entry=KEY2=value2

# Delete secret
php artisan lockbox:delete
```

🔒 Exception Handling
--------------------

[](#-exception-handling)

The library provides specific exceptions for different error types:

```
use Tigusigalpa\YandexLockbox\Exceptions\AuthenticationException;
use Tigusigalpa\YandexLockbox\Exceptions\NotFoundException;
use Tigusigalpa\YandexLockbox\Exceptions\RateLimitException;
use Tigusigalpa\YandexLockbox\Exceptions\ValidationException;
use Tigusigalpa\YandexLockbox\Exceptions\LockboxException;

try {
    $payload = $client->getPayload('secret-id');
} catch (AuthenticationException $e) {
    // Handle 401/403 errors
    echo "Authentication failed: " . $e->getMessage();
} catch (NotFoundException $e) {
    // Handle 404 errors
    echo "Secret not found: " . $e->getMessage();
} catch (RateLimitException $e) {
    // Handle 429 errors
    echo "Rate limit exceeded: " . $e->getMessage();
} catch (ValidationException $e) {
    // Handle 400 errors
    echo "Validation error: " . $e->getMessage();
} catch (LockboxException $e) {
    // Handle other errors
    echo "API error: " . $e->getMessage();
    print_r($e->getContext());
}
```

🧪 Testing
---------

[](#-testing)

### Artisan Commands

[](#artisan-commands)

#### lockbox:test - Comprehensive Testing

[](#lockboxtest---comprehensive-testing)

Runs complete test suite with 8 tests:

```
# Basic run
php artisan lockbox:test

# With specific folder
php artisan lockbox:test --folder=b1g8dn6s4f5h6j7k8l9m

# With automatic cleanup
php artisan lockbox:test --cleanup
```

**Output:**

```
🚀 Testing Yandex Lockbox Connection
==================================================

✓ Test 1: Listing secrets
✓ Test 2: Creating test secret
   Secret ID: e6q7r8s9t0u1v2w3x4y5
✓ Test 3: Getting secret details
✓ Test 4: Adding version with payload
✓ Test 5: Getting secret payload
✓ Test 6: Listing versions
✓ Test 7: Deactivating secret
✓ Test 8: Activating secret

==================================================
✅ Tests passed: 8
🎉 All tests passed successfully!

```

#### lockbox:list - List Secrets

[](#lockboxlist---list-secrets)

```
# List in default folder
php artisan lockbox:list

# List in specific folder
php artisan lockbox:list --folder=b1g8dn6s4f5h6j7k8l9m

# Limit results
php artisan lockbox:list --page-size=10
```

#### lockbox:show - Show Secret Details

[](#lockboxshow---show-secret-details)

```
# Metadata only
php artisan lockbox:show e6q7r8s9t0u1v2w3x4y5

# With payload
php artisan lockbox:show e6q7r8s9t0u1v2w3x4y5 --payload

# Specific version
php artisan lockbox:show e6q7r8s9t0u1v2w3x4y5 --payload --version=version-id
```

#### lockbox:create - Create Secret

[](#lockboxcreate---create-secret)

```
# Simple creation
php artisan lockbox:create my-secret

# With description
php artisan lockbox:create my-secret --description="Production API keys"

# With labels
php artisan lockbox:create my-secret \
  --label=env=production \
  --label=service=api

# With specific folder
php artisan lockbox:create my-secret --folder=b1g8dn6s4f5h6j7k8l9m
```

#### lockbox:add-version - Add Version

[](#lockboxadd-version---add-version)

```
# Interactive mode
php artisan lockbox:add-version e6q7r8s9t0u1v2w3x4y5

# With parameters
php artisan lockbox:add-version e6q7r8s9t0u1v2w3x4y5 \
  --entry=DB_HOST=localhost \
  --entry=DB_USER=admin \
  --entry=DB_PASSWORD=secret

# From JSON file
php artisan lockbox:add-version e6q7r8s9t0u1v2w3x4y5 --file=secrets.json
```

**JSON file format:**

```
{
    "payloadEntries": [
        {
            "key": "API_KEY",
            "textValue": "my-key"
        },
        {
            "key": "API_SECRET",
            "textValue": "my-secret"
        }
    ]
}
```

#### lockbox:delete - Delete Secret

[](#lockboxdelete---delete-secret)

```
# With confirmation
php artisan lockbox:delete e6q7r8s9t0u1v2w3x4y5

# Without confirmation
php artisan lockbox:delete e6q7r8s9t0u1v2w3x4y5 --force
```

### Common Testing Scenarios

[](#common-testing-scenarios)

#### Scenario 1: First Run

[](#scenario-1-first-run)

```
# 1. Check connection
php artisan lockbox:test

# 2. View existing secrets
php artisan lockbox:list

# 3. View specific secret
php artisan lockbox:show  --payload
```

#### Scenario 2: Create New Secret

[](#scenario-2-create-new-secret)

```
# 1. Create secret
php artisan lockbox:create production-db \
  --description="Production database credentials" \
  --label=env=production

# 2. Add values
php artisan lockbox:add-version  \
  --entry=DB_HOST=prod-db.example.com \
  --entry=DB_USER=prod_user \
  --entry=DB_PASSWORD=secure_password

# 3. Verify
php artisan lockbox:show  --payload
```

#### Scenario 3: Update Secret

[](#scenario-3-update-secret)

```
# 1. View current version
php artisan lockbox:show  --payload

# 2. Add new version
php artisan lockbox:add-version  \
  --entry=DB_PASSWORD=new_password

# 3. Verify new version
php artisan lockbox:show  --payload
```

### PHPUnit Tests

[](#phpunit-tests)

```
# Run tests
composer test

# Run tests with coverage
composer test-coverage
```

📚 API Reference
---------------

[](#-api-reference)

### OAuthTokenManager Methods

[](#oauthtokenmanager-methods)

#### Authentication & Token Management

[](#authentication--token-management)

- `getIamToken(): string` - Get IAM token (cached automatically)
- `listClouds(): array` - List all clouds
- `getFirstCloud(): array` - Get first cloud
- `getFirstCloudId(): string` - Get first cloud ID

#### Folder Management

[](#folder-management)

- `listFolders(string $cloudId): array` - List folders in cloud
- `getFolder(string $folderId): array` - Get folder details
- `getFirstFolder(string $cloudId): array` - Get first folder
- `getFirstFolderId(string $cloudId): string` - Get first folder ID
- `getFirstFolderIdFromFirstCloud(): string` - Get first folder ID from first cloud
- `createFolder(string $iamToken, string $cloudId, string $name, ?string $description = null): array` - Create folder

#### Access Control (Permissions)

[](#access-control-permissions)

-

`assignRoleToFolder(string $iamToken, string $folderId, string $subjectId, string $role = 'lockbox.editor', string $subjectType = 'userAccount', bool $waitForCompletion = false, int $maxWaitSeconds = 60): array` - Assign role to folder
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

[](#assignroletofolderstring-iamtoken-string-folderid-string-subjectid-string-role--lockboxeditor-string-subjecttype--useraccount-bool-waitforcompletion--false-int-maxwaitseconds--60-array--assign-role-to-folder)

`listFolderAccessBindings(string $iamToken, string $folderId, int $pageSize = 100, ?string $pageToken = null): array` - List folder access bindings (paginated)

- `getAllFolderAccessBindings(string $iamToken, string $folderId): array` - Get all folder access bindings ( auto-pagination)

#### User Management

[](#user-management)

- `getUserByLogin(string $login): array` - Get full user info by Yandex login
- `getUserIdByLogin(string $login): string` - Get user ID (Subject ID) by Yandex login

#### Async Operations

[](#async-operations)

-

`waitForOperation(string $iamToken, string $operationId, int $maxWaitSeconds = 60, int $pollIntervalSeconds = 2): array` - Wait for operation to complete

- `getOperation(string $iamToken, string $operationId): array` - Get operation status

### Client Methods

[](#client-methods)

#### Secret Management

[](#secret-management)

- `listSecrets(string $folderId): array` - List secrets in folder
- `getSecret(string $secretId): array` - Get secret metadata
- `createSecret(array $data): array` - Create new secret
- `updateSecret(string $secretId, array $data): array` - Update secret
- `deleteSecret(string $secretId): void` - Delete secret

#### Version Management

[](#version-management)

- `addVersion(string $secretId, array $data): array` - Add new version to secret
- `getPayload(string $secretId, ?string $versionId = null): array` - Get secret payload

📝 Requirements
--------------

[](#-requirements)

- PHP 8.0 or higher
- Laravel 8.x - 12.x (optional, for Laravel integration)
- Guzzle HTTP client 7.x or 8.x

🤝 Contributing
--------------

[](#-contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

📄 License
---------

[](#-license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

👤 Author
--------

[](#-author)

**Igor Sazonov**

- GitHub: [@tigusigalpa](https://github.com/tigusigalpa)
- Email:

🔗 Links
-------

[](#-links)

- [Packagist](https://packagist.org/packages/tigusigalpa/yandex-lockbox-php)
- [GitHub Repository](https://github.com/tigusigalpa/yandex-lockbox-php)
- [Issue Tracker](https://github.com/tigusigalpa/yandex-lockbox-php/issues)
- [Yandex Cloud Documentation](https://yandex.cloud/en/docs/lockbox/)

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance71

Regular maintenance activity

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~21 days

Total

2

Last Release

164d ago

Major Versions

v1.0.0 → v2.0.12025-11-29

### Community

Maintainers

![](https://www.gravatar.com/avatar/76c3a1d93c3213a8a22b4b637708d8b66a1ba3a5252624046cae7683a198b3a8?d=identicon)[tigusigalpa](/maintainers/tigusigalpa)

---

Top Contributors

[![tigusigalpa](https://avatars.githubusercontent.com/u/2721390?v=4)](https://github.com/tigusigalpa "tigusigalpa (5 commits)")

---

Tags

apilaravellockboxphpphp8yandexyandex-cloudphpclientlaravelsdkyandexsecretslockbox

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/tigusigalpa-yandex-lockbox-php/health.svg)

```
[![Health](https://phpackages.com/badges/tigusigalpa-yandex-lockbox-php/health.svg)](https://phpackages.com/packages/tigusigalpa-yandex-lockbox-php)
```

###  Alternatives

[openai-php/laravel

OpenAI PHP for Laravel is a supercharged PHP API client that allows you to interact with the Open AI API

3.7k7.6M74](/packages/openai-php-laravel)[google-gemini-php/laravel

Google Gemini PHP for Laravel is a supercharged PHP API client that allows you to interact with the Google Gemini AI API

614397.1k4](/packages/google-gemini-php-laravel)[mozex/anthropic-laravel

Anthropic PHP for Laravel is a supercharged PHP API client that allows you to interact with the Anthropic API

71226.4k1](/packages/mozex-anthropic-laravel)[resend/resend-laravel

Resend for Laravel

1191.4M6](/packages/resend-resend-laravel)[resend/resend-php

Resend PHP library.

564.7M21](/packages/resend-resend-php)[gemini-api-php/laravel

Gemini API client for Laravel

8915.7k](/packages/gemini-api-php-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)