PHPackages                             titoshadow/ansible-vault - 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. [Utility & Helpers](/categories/utility)
4. /
5. titoshadow/ansible-vault

ActiveLibrary[Utility & Helpers](/categories/utility)

titoshadow/ansible-vault
========================

A PHP wrapper for the ansible-vault command.

v1.0.5(1w ago)11.1k↓60%MITPHPPHP ^8.3 || ^8.4 || ^8.5CI passing

Since Jan 20Pushed 1w ago1 watchersCompare

[ Source](https://github.com/titoshadow/ansible-vault)[ Packagist](https://packagist.org/packages/titoshadow/ansible-vault)[ RSS](/packages/titoshadow-ansible-vault/feed)WikiDiscussions master Synced 2d ago

READMEChangelogDependencies (10)Versions (10)Used By (0)

Ansible Vault PHP Wrapper
=========================

[](#ansible-vault-php-wrapper)

[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](LICENSE) [![Tests](https://github.com/titoshadow/ansible-vault/actions/workflows/tests.yml/badge.svg)](https://github.com/titoshadow/ansible-vault/actions/workflows/tests.yml)[![Coverage](https://camo.githubusercontent.com/6f7989c0345c7da1de4e954e13d4d370256329bbc06fceb8218e5f2c81234e05/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f7469746f736861646f772f616e7369626c652d7661756c742e737667)](https://codecov.io/gh/titoshadow/ansible-vault)

A pragmatic, secure wrapper around `ansible-vault` for encrypting/decrypting strings and files, editing vaults, and re-keying from PHP. Tailored for host-centric workflows like storing SSH passwords that Ansible uses to connect to remote hosts.

Requirements
------------

[](#requirements)

- PHP 8.3 or later
- Ansible 2.10+ (`ansible-vault` available on the system)

Binary resolution and availability check
----------------------------------------

[](#binary-resolution-and-availability-check)

The wrapper locates `ansible-vault` and validates availability with `--version`.

Resolution order:

1. Constructor argument `binary`
2. Environment variable `ANSIBLE_VAULT_BIN`
3. Fallback to `ansible-vault` in PATH

Installation
------------

[](#installation)

Ensure Ansible is installed and configured correctly before using this library.

You can install this library via Composer:

```
composer require titoshadow/ansible-vault
```

Usage
-----

[](#usage)

Include the library in your PHP code:

```
use Titoshadow\AnsibleVault\AnsibleVault;

...

// Default (uses PATH) $vault = new AnsibleVault();
// Custom binary path $vault = new AnsibleVault(binary: '/usr/local/bin/ansible-vault');
// Or via environment putenv('ANSIBLE_VAULT_BIN=/opt/ansible/ansible-vault'); $vault = new AnsibleVault();
// Create an instance of the library

$vault = new AnsibleVault('/path/to/vault-password-file');
```

Security model and password handling
------------------------------------

[](#security-model-and-password-handling)

- Avoid plaintext passwords on the command line. This wrapper:
    - Writes provided password strings to secure temp files (0600 on POSIX) and passes `--vault-password-file`.
    - Supports user-provided password file paths as-is.
- Errors scrub secrets in both `--flag value` and `--flag=value` forms (covers `--vault-password`, `--vault-password-file`, `--password`, `-p`, etc.).

Command execution settings
--------------------------

[](#command-execution-settings)

All commands run via a lightweight executor that supports:

- Default timeout (60s) and default working directory (null)
- Per-call override for timeout and cwd (used internally)
- TTY for interactive edit sessions

Configure defaults when needed:

```
use Titoshadow\AnsibleVault\CommandExecutor;
use Titoshadow\AnsibleVault\AnsibleVault;

$executor = new CommandExecutor(defaultTimeout: 120.0, defaultCwd: '/srv/project');
$vault = new AnsibleVault(executor: $executor);
```

Core methods
------------

[](#core-methods)

### Encrypt a String (stdin-name control):

[](#encrypt-a-string-stdin-name-control)

```
// stdin-name defaults to "secret"
$encrypted = $vault->encryptString('Sensitive data', password: 'vault_pwd');
// Custom name to make output variable-friendly
$encrypted = $vault->encryptString('Sensitive data', password: 'vault_pwd', stdinName: 'my_secret');
```

### Decrypt a String

[](#decrypt-a-string)

```
$decryptedString = $vault->decryptString($encrypted, password: 'vault_pwd');
```

### Encrypt a File

[](#encrypt-a-file)

```
vault->encrypt('/path/plain.txt', password: 'vault_pwd');
// or with an existing password
filevault->encrypt('/path/plain.txt', vaultPasswordFile: '/path/vault.pass');
```

### Decrypt a File

[](#decrypt-a-file)

```
$vault->decrypt('/path/secret.txt', password: 'vault_pwd')
```

### Create a Vault

[](#create-a-vault)

```
$vault->create('/path/vault.yml', password: 'vault_pwd', encrypted: true);
```

### Edit a Vault

[](#edit-a-vault)

```
$vault->edit('/path/vault.yml', password: 'vault_pwd');
```

### Rekey a Vault

[](#rekey-a-vault)

```
$vault->rekey('/path/vault.yml', oldPassword: 'old', newPassword: 'new')
```

### Remove a Vault

[](#remove-a-vault)

```
$vault->remove('/path/vault.yml');
```

Host-centric SSH helpers
------------------------

[](#host-centric-ssh-helpers)

Encrypt an SSH password to the conventional variable `ansible_ssh_pass` (in-memory):

```
use Titoshadow\AnsibleVault\CommandExecutor;
use Titoshadow\AnsibleVault\Encrypter;
$encrypter = new Encrypter(new CommandExecutor());
$encrypted = encrypter->encryptSshPasswordVar('ssh_password', password: 'vault_pwd');
//encrypted starts with "$ANSIBLE_VAULT;"
```

Encrypt and write the SSH secret to a file (directories are created if missing):

Exceptions and error handling
-----------------------------

[](#exceptions-and-error-handling)

On failures, a sanitized exception is thrown:

- VaultCliUsageException — typically exit code 2 (CLI misuse, invalid flags)
- VaultAuthException — typically exit code 4 (authentication/decryption issues)
- VaultExecutionException — default/fallback with masked secrets

```
use Titoshadow\AnsibleVault\Exception\VaultAuthException;
use Titoshadow\AnsibleVault\Exception\VaultCliUsageException;
use Titoshadow\AnsibleVault\Exception\VaultExecutionException;

try {
    $vault->decrypt('/path/secret.txt', password: 'wrong');
} catch (VaultAuthExceptione) {
// wrong password
} catch (VaultCliUsageException e) {
 // invalid CLI usage
} catch (VaultExecutionExceptione) {
// generic error (message is sanitized)
}
```

###  Health Score

50

—

FairBetter than 95% of packages

Maintenance98

Actively maintained with recent releases

Popularity19

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity62

Established project with proven stability

 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 ~104 days

Total

6

Last Release

8d ago

PHP version history (2 changes)1.0.0PHP ^8.3

v1.0.5PHP ^8.3 || ^8.4 || ^8.5

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/8121774?v=4)[Jorge](/maintainers/titoshadow)[@titoshadow](https://github.com/titoshadow)

---

Top Contributors

[![titoshadow](https://avatars.githubusercontent.com/u/8121774?v=4)](https://github.com/titoshadow "titoshadow (33 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Rector

Type Coverage Yes

### Embed Badge

![Health badge](/badges/titoshadow-ansible-vault/health.svg)

```
[![Health](https://phpackages.com/badges/titoshadow-ansible-vault/health.svg)](https://phpackages.com/packages/titoshadow-ansible-vault)
```

###  Alternatives

[friendsofphp/php-cs-fixer

A tool to automatically fix PHP code style

13.5k251.2M25.2k](/packages/friendsofphp-php-cs-fixer)[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.7k38.9k](/packages/matomo-matomo)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

751291.4k43](/packages/civicrm-civicrm-core)[spatie/laravel-export

Create a static site bundle from a Laravel app

674146.0k6](/packages/spatie-laravel-export)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k15](/packages/tempest-framework)[phpactor/phpactor

PHP refactoring and intellisense tool for text editors

1.9k17.1k1](/packages/phpactor-phpactor)

PHPackages © 2026

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