Support CSV column headers written unquoted

Author: craig410

CHANGELOG.md

@@ -1,5 +1,9 @@
 ### Unreleased
 
+### v2.3.0 (2025-03-10)
+
+* Support CSV column headers being written unquoted with optional parameter to CSVWriter
+
 ### v2.2.0 (2024-11-14)
 
 * Add `->ago()` and `->future()` helper methods to RealtimeClock

src/CSV/CSVWriter.php

@@ -8,6 +8,7 @@
 
 
 use Ingenerator\PHPUtils\CSV\MismatchedSchemaException;
+use RuntimeException;
 
 class CSVWriter
 {
@@ -28,11 +29,9 @@ class CSVWriter
      */
     protected $expect_schema;
 
-    /**
-     * @var array
-     */
-    protected $options = [
-        'write_utf8_bom' => FALSE
+    protected array $options = [
+        'write_utf8_bom' => FALSE,
+        'quote_headers' => TRUE,
     ];
 
     /**
@@ -72,7 +71,7 @@ public function write(array $row)
                 \fputs($this->resource, static::UTF8_BOM);
             }
             $this->expect_schema = $row_schema;
-            \fputcsv($this->resource, $this->expect_schema);
+            $this->writeHeaders($this->expect_schema);
         } elseif ($this->expect_schema !== $row_schema) {
             throw MismatchedSchemaException::forSchema($this->expect_schema, $row_schema);
         }
@@ -97,4 +96,20 @@ public function close()
 
         $this->resource = NULL;
     }
+
+    private function writeHeaders(array $keys): void
+    {
+        if ($this->options['quote_headers']) {
+            \fputcsv($this->resource, $keys);
+        } else {
+            array_walk(
+                $keys,
+                fn(string $str) => ! str_contains($str, ',')
+                    ?: throw new RuntimeException(
+                        "Column header `$str` cannot contain comma if headers are not quoted"
+                    )
+            );
+            fwrite($this->resource, implode(',', $keys).PHP_EOL);
+        }
+    }
 }

test/unit/CSV/CSVWriterTest.php

@@ -11,8 +11,10 @@
 use Ingenerator\PHPUtils\CSV\CSVWriter;
 use Ingenerator\PHPUtils\CSV\MismatchedSchemaException;
 use LogicException;
+use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\Attributes\TestWith;
 use PHPUnit\Framework\TestCase;
+use RuntimeException;
 use function fclose;
 use function fgetcsv;
 use function file_get_contents;
@@ -134,6 +136,64 @@ public function test_it_does_not_write_column_headers_before_subsequent_rows()
         fclose($file);
     }
 
+    public static function providerQuotedHeaders(): array
+    {
+        $row = ['our data' => 'is at times', 'really big' => 'often'];
+
+        return [
+            'default (with quotes)' => [
+                $row,
+                [],
+                <<<CSV
+                "our data","really big"
+                "is at times",often
+
+                CSV,
+            ],
+            'with quotes' => [
+                $row,
+                ['quote_headers' => true],
+                <<<CSV
+                "our data","really big"
+                "is at times",often
+
+                CSV,
+            ],
+            'without quotes' => [
+                $row,
+                ['quote_headers' => false],
+                <<<CSV
+                our data,really big
+                "is at times",often
+
+                CSV,
+            ],
+        ];
+    }
+
+    #[DataProvider('providerQuotedHeaders')]
+    public function test_it_optionally_writes_column_headers_without_quotes(array $row, array $options, string $expect): void
+    {
+        $file = fopen('php://memory', 'w');
+        $subj = $this->newSubject();
+        $subj->open($file, $options);
+        $subj->write($row);
+        rewind($file);
+        $this->assertSame($expect, stream_get_contents($file));
+        fclose($file);
+    }
+
+    public function test_it_throws_if_column_headers_contain_comma_when_unquoted(): void
+    {
+        $file = fopen('php://memory', 'w');
+        $subj = $this->newSubject();
+        $subj->open($file, ['quote_headers' => false]);
+        $this->expectException(RuntimeException::class);
+        $this->expectExceptionMessage('Column header `really, really big` cannot contain comma if headers are not quoted');
+        $subj->write(['our data' => 'is, at times', 'really, really big' => 'often']);
+        fclose($file);
+    }
+
     #[TestWith([true])]
     #[TestWith([false])]
     public function test_it_optionally_writes_byte_order_mark_at_start_of_file($write_bom)
@@ -189,8 +249,7 @@ protected function assertCSVContent(array $expect, $file)
         $this->assertSame($expect, $actual, 'CSV content should match');
     }
 
-
-    protected function newSubject()
+    private function newSubject(): CSVWriter
     {
         return new CSVWriter();
     }