README

Atomic file writes with temp-file swap and file locking.

Requirements

• PHP 8.2+

Installation

composer require philiprehberger/safe-file-writer

Usage

Write a file atomically

use PhilipRehberger\SafeFileWriter\SafeFile;

// Writes to a temp file first, then renames — atomic on POSIX systems
SafeFile::write('/path/to/config.txt', 'key=value');

// Parent directories are created automatically
SafeFile::write('/path/to/deep/nested/file.txt', 'content');

Write JSON

SafeFile::writeJson('/path/to/data.json', [
    'name' => 'Philip',
    'scores' => [10, 20, 30],
]);
// Writes pretty-printed JSON with a trailing newline

// Custom JSON flags
SafeFile::writeJson('/path/to/compact.json', $data, JSON_UNESCAPED_UNICODE);

Append to a file

// Appends with exclusive lock; creates file if it doesn't exist
SafeFile::append('/var/log/app.log', "[2026-03-13] Info: started\n");
SafeFile::append('/var/log/app.log', "[2026-03-13] Info: finished\n");

Read a file

// Reads with a shared lock
$content = SafeFile::read('/path/to/config.txt');

Read JSON

$data = SafeFile::readJson('/path/to/data.json');
// Returns decoded array/object

Check existence

if (SafeFile::exists('/path/to/file.txt')) {
    // ...
}

Delete a file

$deleted = SafeFile::delete('/path/to/file.txt');
// Returns true if deleted, false if file didn't exist

Backup Before Write

use PhilipRehberger\SafeFileWriter\SafeFile;

// Backs up existing file with timestamp, then writes new content atomically
SafeFile::writeWithBackup('/path/to/config.txt', 'new config');
// Creates /path/to/config.txt.2026-03-31T120000.bak before overwriting

// Store backups in a custom directory
SafeFile::writeWithBackup('/path/to/config.txt', 'updated', '/var/backups');

// Same for JSON files
SafeFile::writeJsonWithBackup('/path/to/data.json', ['version' => 2]);

File Checksums

use PhilipRehberger\SafeFileWriter\Checksum;
use PhilipRehberger\SafeFileWriter\SafeFile;

// Compute a SHA-256 checksum (default)
$hash = SafeFile::checksum('/path/to/file.txt');

// Use a different algorithm
$md5 = SafeFile::checksum('/path/to/file.txt', 'md5');

// Verify a file against a known checksum
$valid = SafeFile::verifyChecksum('/path/to/file.txt', $expectedHash);

// Compare two files
$same = Checksum::compareFiles('/path/to/a.txt', '/path/to/b.txt');

Atomic Multi-File Writes

use PhilipRehberger\SafeFileWriter\SafeFile;

// Write multiple files atomically — all or nothing
SafeFile::writeMany([
    '/path/to/config.json' => '{"key": "value"}',
    '/path/to/settings.yaml' => 'debug: true',
    '/path/to/version.txt' => '1.1.0',
]);
// If any file fails to write, previously written files are rolled back

API

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT