JSON Lines Export Stream Plan

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

/**
 * JSON Lines Export Stream Plan.
 *
 * Purpose:
 * Prepares the non-output parts of a JSON Lines export so the controller can
 * stream one encoded record per line without buffering a large dataset.
 *
 * @param string $base_filename Base filename without extension.
 * @param int $chunk_size Number of records to read per storage chunk.
 * @param array $fields Field names that should be exported.
 * @return array Export stream plan for a controller.
 */
function ogSnippetJsonLinesExportStreamPlan(string $base_filename, int $chunk_size, array $fields): array {
	$clean_filename = preg_replace('/[^a-zA-Z0-9_-]/', '-', trim($base_filename));
	$approved_fields = array();

	if ($clean_filename === '') {
		$clean_filename = 'json-lines-export';
	}

	if ($chunk_size < 1) {
		$chunk_size = 100;
	}

	if ($chunk_size > 5000) {
		$chunk_size = 5000;
	}

	foreach ($fields as $field_name) {
		$clean_field = trim((string) $field_name);

		if ($clean_field !== '') {
			$approved_fields[$clean_field] = $clean_field;
		}
	}

	return array(
		'filename' => $clean_filename.'.jsonl',
		'content_type' => 'application/x-ndjson',
		'chunk_size' => $chunk_size,
		'fields' => array_values($approved_fields),
		'line_flags' => JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
	);
}

$export_plan = ogSnippetJsonLinesExportStreamPlan('expanse-ship-registry', 750, array('ship', 'owner', 'transponder'));

if ($export_plan['chunk_size'] <= 1000) {
	echo 'The Expanse JSON Lines export plan is ready for '.$export_plan['filename'].'.';
} else {
	echo 'The Expanse JSON Lines export needs a smaller chunk size.';
}