PHP File Handling — Missing fclose() Kills Batch Job

<?php

namespace Io\Thecodeforge\FileHandling;

$logFilePath = __DIR__ . '/app.log';

// Attempt to open the file in append mode.
// 'a' means: write-only, pointer starts at END of file,
// creates the file if it doesn't exist yet.
$fileHandle = fopen($logFilePath, 'a');

// ALWAYS check the return value — fopen() returns false on failure.
// This happens when: the file path is wrong, permissions are denied,
// or the process has too many open handles.
if ($fileHandle === false) {
    // die() stops execution and tells us exactly what went wrong.
    die('Could not open log file at: ' . $logFilePath);
}

// Build a timestamped log entry — a real-world pattern used in every app.
$timestamp   = date('Y-m-d H:i:s');
$logMessage  = "[{$timestamp}] Application started successfully." . PHP_EOL;

// fwrite() writes the string to the file at the current pointer position.
// PHP_EOL adds the correct newline for the current OS (\n on Linux, \r\n on Windows).
$bytesWritten = fwrite($fileHandle, $logMessage);

if ($bytesWritten === false) {
    // The handle was valid but the write still failed (e.g., disk full).
    fclose($fileHandle); // Close before dying — honor the contract.
    die('Failed to write to log file.');
}

echo "Wrote {$bytesWritten} bytes to {$logFilePath}" . PHP_EOL;

// ALWAYS close the handle when you're done.
// This flushes any buffered data to disk and releases the file descriptor.
fclose($fileHandle);

echo 'File handle closed cleanly.' . PHP_EOL;

<?php

namespace Io\Thecodeforge\FileHandling;

// ─── METHOD 1: file_get_contents() ───────────────────────────────────────────
// Best for: small files where you need the full content as a string.
// Worst for: large files — it loads everything into RAM at once.

$configFilePath = __DIR__ . '/config.json';

if (!file_exists($configFilePath)) {
    die('Config file not found: ' . $configFilePath);
}

$configJson   = file_get_contents($configFilePath);
$configData   = json_decode($configJson, associative: true);

echo 'App name from config: ' . ($configData['app_name'] ?? 'unknown') . PHP_EOL;


// ─── METHOD 2: fgets() in a loop ─────────────────────────────────────────────
// Best for: large files — memory stays flat because only one line is in RAM.
// Real-world use: processing large CSVs, parsing log files, reading data feeds.

$logFilePath = __DIR__ . '/app.log';

$fileHandle = fopen($logFilePath, 'r'); // 'r' = read-only, pointer at START

if ($fileHandle === false) {
    die('Cannot open log file for reading: ' . $logFilePath);
}

$lineNumber    = 0;
$errorCount    = 0;
$errorKeyword  = '[ERROR]';

// feof() returns true only AFTER a read hits the end — so check it after reading.
while (($currentLine = fgets($fileHandle)) !== false) {
    $lineNumber++;

    // Trim trailing whitespace/newline characters before processing.
    $trimmedLine = rtrim($currentLine);

    // Count lines that contain our error keyword — a real log-analysis pattern.
    if (str_contains($trimmedLine, $errorKeyword)) {
        $errorCount++;
        echo "Line {$lineNumber} has an error: {$trimmedLine}" . PHP_EOL;
    }
}

// Check if the loop ended because of an error, not just EOF.
if (!feof($fileHandle)) {
    echo 'Warning: Loop ended unexpectedly — possible read error.' . PHP_EOL;
}

fclose($fileHandle);

echo PHP_EOL . "Scan complete. Found {$errorCount} error(s) in {$lineNumber} lines." . PHP_EOL;

<?php

namespace Io\Thecodeforge\FileHandling;

// ─── SCENARIO 1: Generate a fresh CSV report (use 'w' — we want a clean file) ─

$reportFilePath = __DIR__ . '/weekly_report.csv';

$reportHandle = fopen($reportFilePath, 'w');

if ($reportHandle === false) {
    die('Cannot create report file: ' . $reportFilePath);
}

// Write the CSV header row first.
fputcsv($reportHandle, ['Order ID', 'Customer', 'Total', 'Date']);

// Simulate a dataset — in real life this would come from a database query.
$orderRecords = [
    [1001, 'Alice Nguyen',  '89.99',  '2024-03-10'],
    [1002, 'Bob Castillo',  '145.50', '2024-03-11'],
    [1003, 'Carol Okafor', '32.00',  '2024-03-11'],
];

foreach ($orderRecords as $order) {
    // fputcsv() handles quoting and escaping automatically — don't build CSV by hand.
    fputcsv($reportHandle, $order);
}

fclose($reportHandle);
echo 'Report written to: ' . $reportFilePath . PHP_EOL;


// ─── SCENARIO 2: Append a structured event to an audit log (use 'a') ──────────

$auditLogPath = __DIR__ . '/audit.log';

// file_put_contents() with FILE_APPEND is a one-liner for simple appends.
// It handles open, write, and close internally — perfect for quick log writes.
$auditEntry = sprintf(
    '[%s] User #%d (%s) performed action: %s' . PHP_EOL,
    date('Y-m-d H:i:s'),
    42,
    'alice@example.com',
    'EXPORT_REPORT'
);

$bytesWritten = file_put_contents($auditLogPath, $auditEntry, FILE_APPEND | LOCK_EX);
// LOCK_EX acquires an exclusive lock during the write — critical if multiple
// requests could write to the same log file at the same time (race condition).

if ($bytesWritten === false) {
    echo 'Audit log write failed.' . PHP_EOL;
} else {
    echo "Audit entry written ({$bytesWritten} bytes)." . PHP_EOL;
}

<?php

namespace Io\Thecodeforge\FileHandling;

$uploadedFilePath = __DIR__ . '/uploads/user_data.csv';
$backupFilePath   = __DIR__ . '/backups/user_data_' . date('Ymd_His') . '.csv';
$maxSafeFileSize  = 1 * 1024 * 1024; // 1 MB in bytes — our streaming threshold

// ─── STEP 1: Does the file actually exist? ────────────────────────────────────
if (!file_exists($uploadedFilePath)) {
    die('Uploaded file not found: ' . $uploadedFilePath);
}

// ─── STEP 2: Can we read it? (Permissions check) ─────────────────────────────
if (!is_readable($uploadedFilePath)) {
    die('Permission denied — cannot read: ' . $uploadedFilePath);
}

// ─── STEP 3: How big is it? (Decide how to read it) ─────────────────────────
$fileSizeBytes = filesize($uploadedFilePath);
$fileSizeKb    = round($fileSizeBytes / 1024, 2);

echo "File size: {$fileSizeKb} KB" . PHP_EOL;

if ($fileSizeBytes > $maxSafeFileSize) {
    echo 'Large file detected — will use streaming (fgets) to protect memory.' . PHP_EOL;
} else {
    echo 'Small file — safe to load entirely with file_get_contents.' . PHP_EOL;
}

// ─── STEP 4: Back it up before processing ────────────────────────────────────
// copy() leaves the original intact. rename() would move it (destructive).
if (!copy($uploadedFilePath, $backupFilePath)) {
    die('Backup failed — aborting to protect original data.');
}

echo 'Backup created at: ' . $backupFilePath . PHP_EOL;

// ─── STEP 5: Clean up temp files older than 7 days ───────────────────────────
$tempDir      = __DIR__ . '/tmp';
$maxAgeInDays = 7;
$cutoffTime   = time() - ($maxAgeInDays * 24 * 60 * 60);

foreach (glob($tempDir . '/*.tmp') as $tempFile) {
    // filemtime() returns the Unix timestamp of the last modification.
    if (filemtime($tempFile) < $cutoffTime) {
        unlink($tempFile); // Delete the stale temp file.
        echo 'Deleted stale temp file: ' . basename($tempFile) . PHP_EOL;
    }
}

echo 'File utility checks complete.' . PHP_EOL;

<?php

namespace Io\Thecodeforge\FileHandling;

/**
 * Safely read a file's contents with error checking.
 * Throws RuntimeException on failure so you can handle it in one place.
 */
function safeFileGetContents(string $path): string
{
    if (!file_exists($path)) {
        throw new \RuntimeException("File does not exist: $path");
    }
    if (!is_readable($path)) {
        throw new \RuntimeException("File not readable: $path");
    }
    $contents = file_get_contents($path);
    if ($contents === false) {
        throw new \RuntimeException("Failed to read file: $path");
    }
    return $contents;
}

/**
 * Safely write contents to a file with directory creation.
 */
function safeFilePutContents(string $path, string $data, int $flags = 0): int
{
    $dir = dirname($path);
    if (!is_dir($dir)) {
        if (!mkdir($dir, 0755, true)) {
            throw new \RuntimeException("Could not create directory: $dir");
        }
    }
    $bytes = file_put_contents($path, $data, $flags);
    if ($bytes === false) {
        throw new \RuntimeException("Failed to write to file: $path");
    }
    return $bytes;
}

// Example usage:
try {
    $contents = safeFileGetContents(__DIR__ . '/config.json');
    $written = safeFilePutContents(__DIR__ . '/output.txt', $contents, LOCK_EX);
    echo "Success: $written bytes written." . PHP_EOL;
} catch (\RuntimeException $e) {
    error_log($e->getMessage());
    echo "Error: " . $e->getMessage() . PHP_EOL;
}