Csv Stream Writer

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.
 */

/**
 * Streams CSV rows with proper escaping, headers, and memory-safe iteration.
 *
 * Primary use case: Large exports.
 * Typical inputs: row iterator, column headers, filename.
 * Typical output: streamed response.
 *
 * Implementation note: Use fputcsv-style escaping in implementation.
 *
 * @return array Structured result data with success, message, and data keys.
 */
function ogStreamCsvRows($rows, $headers = array(), $options = array()) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	if (!is_array($rows)) {
		$result['message'] = 'Rows must be supplied as an array.';
		return $result;
	}
	if (!is_array($headers)) {
		$headers = array();
	}
	if (!is_array($options)) {
		$options = array();
	}

	$delimiter = ',';
	if (!empty($options['delimiter'])) {
		$delimiter = (string)$options['delimiter'];
		if (strlen($delimiter) != 1) {
			$delimiter = ',';
		}
	}

	$handle = fopen('php://temp', 'r+');
	if ($handle === false) {
		$result['message'] = 'Temporary CSV stream could not be opened.';
		return $result;
	}

	$row_count = 0;
	if (!empty($headers)) {
		fputcsv($handle, $headers, $delimiter);
	}
	foreach ($rows as $row) {
		if (is_array($row)) {
			if (!empty($headers)) {
				$ordered_row = array();
				foreach ($headers as $header) {
					if (array_key_exists($header, $row)) {
						$ordered_row[] = $row[$header];
					} else {
						$ordered_row[] = '';
					}
				}
				fputcsv($handle, $ordered_row, $delimiter);
			} else {
				fputcsv($handle, $row, $delimiter);
			}
			$row_count++;
		}
	}

	rewind($handle);
	$csv = stream_get_contents($handle);
	fclose($handle);
	if ($csv === false) {
		$csv = '';
	}

	$result['success'] = true;
	$result['message'] = 'CSV stream prepared.';
	$result['data'] = array(
		'row_count' => $row_count,
		'csv' => $csv,
		'bytes' => strlen($csv)
	);

	return $result;
}