Write to a File with file_put_contents

Code

<?php

/*
 * Copyright (c) 2026 Jeffery L. Paris <jparis@phpog.com>.
 * Free for personal and internal use. Paid project use requires visible credit
 * to Jeffery L. Paris. Corporate use requires a paid license fee unless a
 * separate written license states otherwise.
 */

/**
 * Write to a File with file_put_contents.
 *
 * Purpose:
 * Writes plain text to an approved directory with a strict filename rule and
 * an exclusive file lock.
 *
 * @param string $base_directory Approved directory root.
 * @param string $file_name Safe file name only, not a path.
 * @param string $contents Text to write.
 * @return array Write status, byte count, and public message.
 */
function ogSnippetWriteToAFileWithFilePutContents(string $base_directory, string $file_name, string $contents): array {
	$base_directory = rtrim($base_directory, DIRECTORY_SEPARATOR);
	$file_name = trim($file_name);

	if ($base_directory === '' || $file_name === '') {
		return array('success' => false, 'bytes' => 0, 'message' => 'Directory and file name are required.');
	}

	if (preg_match('/^[a-zA-Z0-9._-]+$/', $file_name) !== 1) {
		return array('success' => false, 'bytes' => 0, 'message' => 'File name contains unsupported characters.');
	}

	$real_base = realpath($base_directory);

	if ($real_base === false || is_dir($real_base) === false || is_writable($real_base) === false) {
		return array('success' => false, 'bytes' => 0, 'message' => 'Approved directory is not writable.');
	}

	$target_path = $real_base.DIRECTORY_SEPARATOR.$file_name;
	$bytes_written = file_put_contents($target_path, $contents, LOCK_EX);

	if ($bytes_written === false) {
		return array('success' => false, 'bytes' => 0, 'message' => 'File write failed.');
	}

	return array(
		'success' => true,
		'bytes' => (int) $bytes_written,
		'message' => 'File write completed.'
	);
}

$mission_note = "Rocinante supply manifest checked.
Nostromo quarantine lock remains sealed.
";
$result = ogSnippetWriteToAFileWithFilePutContents(__DIR__, 'og-mission-note.txt', $mission_note);

print_r($result);