Merge pull request #174 from parsecsv/code-quality-and-documentation

Code quality and documentation

.travis.yml

@@ -1,4 +1,5 @@
 language: php
+dist: trusty
 
 php:
   - '7.3'

src/Csv.php

@@ -169,7 +169,7 @@ class Csv {
 
     /**
      * Convert Encoding
-     * Should we convert the csv encoding?
+     * Should we convert the CSV character encoding?
      *
      * @var bool
      */
@@ -278,8 +278,20 @@ class Csv {
     public $error_info = array();
 
     /**
-     * Titles
+     * $titles has 4 distinct tasks:
-     * CSV titles if they exists
+     * 1. After reading in CSV data, $titles will contain the column headers
+     *    present in the data.
+     *
+     * 2. It defines which fields from the $data array to write e.g. when
+     *    calling unparse(), and in which order. This lets you skip columns you
+     *    don't want in your output, but are present in $data.
+     *    See examples/save_to_file_without_header_row.php.
+     *
+     * 3. It lets you rename columns. See StreamTest::testWriteStream for an
+     *    example.
+     *
+     * 4. When writing data and $header is true, then $titles is also used for
+     *    the first row.
      *
      * @var array
      */
@@ -400,6 +412,7 @@ class Csv {
      *                        $this->titles would be used instead.
      *
      * @return bool
+     *   True on success
      */
     public function save($file = '', $data = array(), $append = FileProcessingModeEnum::MODE_FILE_OVERWRITE, $fields = array()) {
         if (empty($file)) {
@@ -709,7 +722,7 @@ class Csv {
                 $col++;
 
                 // end of row
-                if ($ch == "\n" || $ch == "\r" || $ch === false) {
+                if (in_array($ch, ["\n", "\r", false], true)) {
                     if ($this->_validate_offset($row_count) && $this->_validate_row_conditions($row, $this->conditions)) {
                         if ($this->heading && empty($head)) {
                             $head = $row;
@@ -832,7 +845,17 @@ class Csv {
         }
 
         if ($this->convert_encoding) {
-            $string = iconv($this->input_encoding, $this->output_encoding, $string);
+            /** @noinspection PhpComposerExtensionStubsInspection
+             *
+             * If you receive an error at the following 3 lines, you must enable
+             * the following PHP extension:
+             *
+             *  - if $use_mb_convert_encoding is true: mbstring
+             *  - if $use_mb_convert_encoding is false: iconv
+             */
+            $string = $this->use_mb_convert_encoding ?
+                mb_convert_encoding($string, $this->output_encoding, $this->input_encoding) :
+                iconv($this->input_encoding, $this->output_encoding, $string);
         }
 
         return $string;
@@ -927,6 +950,14 @@ class Csv {
             }
 
             if ($this->convert_encoding && $this->input_encoding !== $this->output_encoding) {
+                /** @noinspection PhpComposerExtensionStubsInspection
+                 *
+                 * If you receive an error at the following 3 lines, you must enable
+                 * the following PHP extension:
+                 *
+                 *  - if $use_mb_convert_encoding is true: mbstring
+                 *  - if $use_mb_convert_encoding is false: iconv
+                 */
                 $data = $this->use_mb_convert_encoding ?
                     mb_convert_encoding($data, $this->output_encoding, $this->input_encoding) :
                     iconv($this->input_encoding, $this->output_encoding, $data);
@@ -1026,7 +1057,7 @@ class Csv {
             $op = $capture[2];
             $value = $capture[3];
 
-            if (preg_match('/^([\'\"]{1})(.*)([\'\"]{1})$/', $value, $capture) && $capture[1] == $capture[3]) {
+            if (preg_match('/^([\'"])(.*)([\'"])$/', $value, $capture) && $capture[1] == $capture[3]) {
                 $value = strtr($capture[2], array(
                     "\\n" => "\n",
                     "\\r" => "\r",
@@ -1037,7 +1068,8 @@ class Csv {
             }
 
             if (array_key_exists($field, $row)) {
-                if (($op == '=' || $op == 'equals' || $op == 'is') && $row[$field] == $value) {
+                $op_equals = in_array($op, ['=', 'equals', 'is'], true);
+                if ($op_equals && $row[$field] == $value) {
                     return '1';
                 } elseif (($op == '!=' || $op == 'is not') && $row[$field] != $value) {
                     return '1';
@@ -1093,7 +1125,7 @@ class Csv {
                 : '';
             $enclosure_quoted = preg_quote($this->enclosure, '/');
             $pattern = "/" . $delimiter_quoted . $enclosure_quoted . "|\n|\r/i";
-            if ($this->enclose_all || preg_match($pattern, $value) || ($value{0} == ' ' || substr($value, -1) == ' ')) {
+            if ($this->enclose_all || preg_match($pattern, $value) || (strpos($value, ' ') === 0 || substr($value, -1) == ' ')) {
                 $value = str_replace($this->enclosure, $this->enclosure . $this->enclosure, $value);
                 $value = $this->enclosure . $value . $this->enclosure;
             }
@@ -1190,7 +1222,9 @@ class Csv {
      * @param string $mode    fopen() mode
      * @param int    $lock    flock() mode
      *
-     * @return  true or false
+     * @return bool
+     *   True on success
+     *
      */
     protected function _wfile($file, $content = '', $mode = 'wb', $lock = LOCK_EX) {
         if ($fp = fopen($file, $mode)) {

tests/methods/ExampleStream.php

@@ -0,0 +1,101 @@
+<?php
+
+namespace ParseCsv\tests\methods;
+
+/**
+ * This is a very simple implementation of a stream wrapper. All URLs are mapped
+ * to just one buffer. It exists to prove that ParseCsv can read and write
+ * streams.
+ *
+ * @see https://www.php.net/manual/en/class.streamwrapper.php
+ */
+class ExampleStream {
+
+    private static $position = 0;
+
+    private static $stream_content;
+
+    public function stream_open($uri, $mode) {
+        if (strpos($mode, 'a') === false) {
+            self::$position = 0;
+        }
+        if (strpos($mode, 'w') !== false) {
+            self::$stream_content = '';
+        }
+        return true;
+    }
+
+    public function stream_read($count) {
+        $ret = substr(self::$stream_content, self::$position, $count);
+        self::$position += strlen($ret);
+        return $ret;
+    }
+
+    public function stream_write($data) {
+        $left = substr(self::$stream_content, 0, self::$position);
+        $right = substr(self::$stream_content, self::$position + strlen($data));
+        self::$stream_content = $left . $data . $right;
+        self::$position += strlen($data);
+        return strlen($data);
+    }
+
+    public function stream_stat() {
+        return ['size' => strlen(self::$stream_content)];
+    }
+
+
+    public function stream_tell() {
+        return self::$position;
+    }
+
+    public function stream_eof() {
+        return self::$position >= strlen(self::$stream_content);
+    }
+
+    public function url_stat() {
+        return ['size' => strlen(self::$stream_content)];
+    }
+
+    public function stream_seek($offset, $whence) {
+        switch ($whence) {
+            case SEEK_SET:
+                if ($offset < strlen(self::$stream_content) && $offset >= 0) {
+                    self::$position = $offset;
+                    return true;
+                } else {
+                    return false;
+                }
+                break;
+
+            case SEEK_CUR:
+                if ($offset >= 0) {
+                    self::$position += $offset;
+                    return true;
+                } else {
+                    return false;
+                }
+                break;
+
+            case SEEK_END:
+                if (strlen(self::$stream_content) + $offset >= 0) {
+                    self::$position = strlen(self::$stream_content) + $offset;
+                    return true;
+                } else {
+                    return false;
+                }
+                break;
+
+            default:
+                return false;
+        }
+    }
+
+    public function stream_lock($operation) {
+        return true;
+    }
+
+    public function stream_metadata() {
+        return false;
+    }
+}
+

tests/methods/StreamTest.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace ParseCsv\tests\methods;
+
+use ParseCsv\Csv;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Writes roughly 1 MB of data. This is useful because of a limit of 8 KB
+ * encountered with stream operations in certain PHP versions.
+ */
+class StreamTest extends TestCase {
+
+    public function setUp() {
+        static $done;
+        if ($done) {
+            // Make sure we register the stream just once - or PHP will scream.
+            return;
+        }
+
+        stream_wrapper_register("example", ExampleStream::class)
+        or die("Failed to register protocol");
+        $done = 1;
+    }
+
+    public function testReadStream() {
+        $csv = new Csv();
+
+        // Write data to our stream:
+        $filename = 'example://tmp';
+        copy(__DIR__ . '/fixtures/datatype.csv', $filename);
+        $many_dots = str_repeat('.', 1000 * 1000) . ";;;;;\n";
+        file_put_contents($filename, $many_dots, FILE_APPEND);
+
+        self::assertSame(';', $csv->auto(file_get_contents($filename)));
+        self::assertCount(4, $csv->data);
+        self::assertCount(6, reset($csv->data));
+    }
+
+    public function testWriteStream() {
+        $csv = new Csv();
+        $csv->linefeed = "\n";
+        $many_dots = str_repeat('.', 1000 * 1000);
+        $csv->data = [
+            [
+                'Name' => 'Rudolf',
+                'Question' => 'Which color is his nose?',
+            ],
+            [
+                'Name' => 'Sponge Bob',
+                'Question' => 'Which shape are his pants?',
+            ],
+            [
+                'Name' => $many_dots,
+                'Question' => 'Can you count one million dots?',
+            ],
+        ];
+
+        // Just export the first column, but with a new name
+        $csv->titles = ['Name' => 'Character'];
+
+        // Write data to our stream:
+        $filename = 'example://data';
+        copy(__DIR__ . '/fixtures/datatype.csv', $filename);
+
+        self::assertSame(true, $csv->save($filename));
+        $expected = "Character\nRudolf\nSponge Bob\n";
+        $expected .= $many_dots . "\n";
+        self::assertSame($expected, file_get_contents($filename));
+    }
+}