[RFC] Add CSV extension (ext/csv)

ext/csv/LICENSE

@@ -0,0 +1,27 @@
+Copyright © 2020-2026, Gina Peter Banyard and Contributors.
+Copyright © 1999-2019, The PHP Group.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ext/csv/config.m4

@@ -0,0 +1,14 @@
+dnl config.m4 for extension csv
+
+PHP_ARG_ENABLE([csv],
+  [whether to enable CSV support],
+  [AS_HELP_STRING([--disable-csv],
+    [Disable CSV support])],
+  [yes])
+
+if test "$PHP_CSV" != "no"; then
+  AC_DEFINE([HAVE_CSV], [1],
+    [Define to 1 if the PHP extension 'csv' is available.])
+  PHP_NEW_EXTENSION([csv], [csv.c], [$ext_shared])
+  PHP_INSTALL_HEADERS([ext/csv], [php_csv.h])
+fi

ext/csv/config.w32

@@ -0,0 +1,9 @@
+// vim:ft=javascript
+
+ARG_ENABLE("csv", "CSV support", "yes");
+
+if (PHP_CSV != "no") {
+	EXTENSION("csv", "csv.c");
+	AC_DEFINE("HAVE_CSV", 1, "Define to 1 if the PHP extension 'csv' is available.");
+	PHP_INSTALL_HEADERS("ext/csv", "php_csv.h");
+}

ext/csv/csv.stub.php

@@ -0,0 +1,42 @@
+<?php
+
+/** @generate-class-entries */
+
+namespace Csv;
+
+function array_to_row(array $fields, string $delimiter = ',', string $enclosure = '"', string $eolSequence = "\r\n"): string {}
+
+function row_to_array(string $row, string $delimiter = ',', string $enclosure = '"', string $eolSequence = "\r\n"): array {}
+
+function collection_to_buffer(iterable $collection, string $delimiter = ',', string $enclosure = '"', string $eolSequence = "\r\n"): string {}
+
+function collection_to_file(string $file, iterable $collection, string $delimiter = ',', string $enclosure = '"', string $eolSequence = "\r\n"): void {}
+
+function buffer_to_collection(string $buffer, string $delimiter = ',', string $enclosure = '"', string $eolSequence = "\r\n"): array {}
+
+function buffer_to_collection_lax(string $buffer, string $delimiter = ',', string $enclosure = '"', string $eolSequence = "\r\n"): array {}
+
+/**
+ * @not-serializable
+ * @strict-properties
+ */
+final class LazyLaxCollection implements \IteratorAggregate
+{
+    private function __construct() {}
+
+    public function getIterator(): \InternalIterator {}
+
+    public static function createFromBuffer(
+        string $buffer,
+        string $delimiter = ',',
+        string $enclosure = '"',
+        string $eolSequence = "\r\n"
+    ): LazyLaxCollection {}
+
+    public static function createFromFile(
+        string $file,
+        string $delimiter = ',',
+        string $enclosure = '"',
+        string $eolSequence = "\r\n"
+    ): LazyLaxCollection {}
+}

ext/csv/php_csv.h

@@ -0,0 +1,27 @@
+/*
+   +----------------------------------------------------------------------+
+   | Copyright © 2020-2026, Gina Peter Banyard and Contributors.          |
+   +----------------------------------------------------------------------+
+   | This source file is subject to the Modified BSD License that is      |
+   | bundled with this package in the file LICENSE, and is available      |
+   | through the World Wide Web at <https://www.php.net/license/>.        |
+   |                                                                      |
+   | SPDX-License-Identifier: BSD-3-Clause                                |
+   +----------------------------------------------------------------------+
+   | Authors: Gina Peter Banyard <girgias@php.net>                        |
+   |          Damian Jóźwiak <damian.jozwiak.lodz@gmail.com>              |
+   +----------------------------------------------------------------------+
+*/
+/* csv extension for PHP */
+
+#ifndef PHP_CSV_H
+# define PHP_CSV_H
+
+extern zend_module_entry csv_module_entry;
+# define phpext_csv_ptr &csv_module_entry
+
+# if defined(ZTS) && defined(COMPILE_DL_CSV)
+ZEND_TSRMLS_CACHE_EXTERN()
+# endif
+
+#endif	/* PHP_CSV_H */

ext/csv/tests/001_load-csv-extension-check.phpt

@@ -0,0 +1,14 @@
+--TEST--
+Check if csv is loaded
+--SKIPIF--
+<?php
+if (!extension_loaded('csv')) {
+	echo 'skip';
+}
+?>
+--FILE--
+<?php
+echo 'The extension "csv" is available';
+?>
+--EXPECT--
+The extension "csv" is available

ext/csv/tests/LazyCollection/deny_instantiation.phpt

@@ -0,0 +1,20 @@
+--TEST--
+Csv\LazyLaxCollection must not be instantiable
+--SKIPIF--
+<?php
+if (!extension_loaded('csv')) {
+	echo 'skip';
+}
+?>
+--FILE--
+<?php
+
+try {
+    new Csv\LazyLaxCollection();
+} catch (\Throwable $e) {
+    echo $e::class, ': ', $e->getMessage(), \PHP_EOL;
+}
+
+?>
+--EXPECT--
+Error: Cannot instantiate Csv\LazyLaxCollection class

ext/csv/tests/LazyCollection/deny_instantiation_via_reflection.phpt

@@ -0,0 +1,44 @@
+--TEST--
+Csv\LazyLaxCollection must not be instantiable
+--SKIPIF--
+<?php
+if (!extension_loaded('csv')) {
+	echo 'skip';
+}
+?>
+--FILE--
+<?php
+
+$rc = new ReflectionClass('Csv\LazyLaxCollection');
+var_dump($rc);
+
+try {
+    $o = $rc->newInstance();
+    var_dump($o);
+} catch (\Throwable $e) {
+    echo $e::class, ': ', $e->getMessage(), \PHP_EOL;
+}
+
+try {
+    $o = $rc->newInstanceArgs();
+    var_dump($o);
+} catch (\Throwable $e) {
+    echo $e::class, ': ', $e->getMessage(), \PHP_EOL;
+}
+
+try {
+    $o = $rc->newInstanceWithoutConstructor();
+    var_dump($o);
+} catch (\Throwable $e) {
+    echo $e::class, ': ', $e->getMessage(), \PHP_EOL;
+}
+
+?>
+--EXPECT--
+object(ReflectionClass)#1 (1) {
+  ["name"]=>
+  string(21) "Csv\LazyLaxCollection"
+}
+Error: Cannot instantiate Csv\LazyLaxCollection class
+Error: Cannot instantiate Csv\LazyLaxCollection class
+ReflectionException: Class Csv\LazyLaxCollection is an internal class marked as final that cannot be instantiated without invoking its constructor

ext/csv/tests/LazyCollection/fromBuffer/basic.phpt

@@ -0,0 +1,51 @@
+--TEST--
+Test Csv\LazyLaxCollection::createFromBuffer() with standard parameters
+--SKIPIF--
+<?php
+if (!extension_loaded('csv')) {
+	echo 'skip';
+}
+?>
+--FILE--
+<?php
+
+$string = "One,Two,Three\r\nFour,Five,Six\r\nSeven,Eight,Nine\r\n";
+
+$it = Csv\LazyLaxCollection::createFromBuffer($string);
+var_dump($it);
+
+foreach ($it as $nb => $row) {
+    var_dump($nb, $row);
+}
+
+?>
+--EXPECT--
+object(Csv\LazyLaxCollection)#1 (0) {
+}
+int(0)
+array(3) {
+  [0]=>
+  string(3) "One"
+  [1]=>
+  string(3) "Two"
+  [2]=>
+  string(5) "Three"
+}
+int(1)
+array(3) {
+  [0]=>
+  string(4) "Four"
+  [1]=>
+  string(4) "Five"
+  [2]=>
+  string(3) "Six"
+}
+int(2)
+array(3) {
+  [0]=>
+  string(5) "Seven"
+  [1]=>
+  string(5) "Eight"
+  [2]=>
+  string(4) "Nine"
+}

ext/csv/tests/LazyCollection/fromBuffer/lax_varying_field_count.phpt

@@ -0,0 +1,32 @@
+--TEST--
+Csv\LazyLaxCollection::createFromBuffer() is lax: rows may have a varying number of fields
+--SKIPIF--
+<?php
+if (!extension_loaded('csv')) {
+	echo 'skip';
+}
+?>
+--FILE--
+<?php
+
+$string = "One,Two,Three\r\nFour\r\nFive,Six\r\nSeven,Eight,Nine,Ten\r\n";
+
+$collection = Csv\LazyLaxCollection::createFromBuffer($string);
+
+var_dump(iterator_to_array($collection) === [
+    ['One', 'Two', 'Three'],
+    ['Four'],
+    ['Five', 'Six'],
+    ['Seven', 'Eight', 'Nine', 'Ten'],
+]);
+
+try {
+    Csv\buffer_to_collection($string);
+} catch (\ValueError $e) {
+    echo $e::class, ': ', $e->getMessage(), \PHP_EOL;
+}
+
+?>
+--EXPECT--
+bool(true)
+ValueError: Buffer row 2 contains 1 fields compared to 3 fields on previous rows