Explicit email address for security problems

This adds consistency because $csv->parse() does the same.

Fix #200
Fix #201

ChangeLog.txt

@@ -1,3 +1,16 @@
+ParseCSV 1.3.1
+-----------------------------------
+Date: 20-Jun-2021
+
+Bugfix:
+- `parseFile()` will now set `$csv->data`.
+  Until now, the parsed data was only returned.
+  This adds consistency with `$csv->parse()`
+  for the following operations on the object.
+
+-----------------------------------
+
+
 ParseCSV 1.3.0
 -----------------------------------
 Date: 14-Apr-2021

README.md

@@ -53,14 +53,7 @@ To use ParseCSV, you then have to add a `require 'parsecsv.lib.php';` line.
 
 ## Example Usage
 
-**General parsing**
-
-```php
-$csv = new \ParseCsv\Csv('data.csv');
-print_r($csv->data);
-```
-
-**Tab delimited, and encoding conversion**
+**Parse a tab-delimited CSV file with encoding conversion**
 
 ```php
 $csv = new \ParseCsv\Csv();
@@ -70,7 +63,7 @@ $csv->parseFile('data.tsv');
 print_r($csv->data);
 ```
 
-**Auto-detect delimiter character**
+**Auto-detect field delimiter character**
 
 ```php
 $csv = new \ParseCsv\Csv();
@@ -152,6 +145,8 @@ $csv->save('data.csv', array(array('1986', 'Home', 'Nowhere', '')), /* append */
 **Convert 2D array to CSV data and send headers to browser to treat output as
 a file and download it**
 
+Your web app users would call this an export.
+
 ```php
 $csv = new \ParseCsv\Csv();
 $csv->linefeed = "\n";
@@ -173,6 +168,10 @@ composer run test
 When pushing code to GitHub, tests will be executed using Travis CI. The relevant configuration is in the
 file `.travis.yml`.
 
+## Security
+
+If you discover any security related issues, please email ParseCsv@blaeul.de instead of using GitHub issues.
+
 ## Credits
 
 * ParseCsv is based on the concept of [Ming Hong Ng][ming]'s [CsvFileParser][]

src/Csv.php

@@ -49,7 +49,7 @@ class Csv {
      */
 
     /**
-     * Heading
+     * Header row:
      * Use first line/entry as field names
      *
      * @var bool
@@ -57,7 +57,6 @@ class Csv {
     public $heading = true;
 
     /**
-     * Fields
      * Override field names
      *
      * @var array
@@ -65,7 +64,6 @@ class Csv {
     public $fields = array();
 
     /**
-     * Sort By
      * Sort CSV by this field
      *
      * @var string|null
@@ -73,15 +71,13 @@ class Csv {
     public $sort_by = null;
 
     /**
-     * Sort Reverse
-     * Reverse the sort function
+     * Reverse the sort direction
      *
      * @var bool
      */
     public $sort_reverse = false;
 
     /**
-     * Sort Type
      * Sort behavior passed to sort methods
      *
      * regular = SORT_REGULAR
@@ -93,31 +89,34 @@ class Csv {
     public $sort_type = SortEnum::SORT_TYPE_REGULAR;
 
     /**
-     * Delimiter
-     * Delimiter character
+     * Field delimiter character
      *
      * @var string
      */
     public $delimiter = ',';
 
     /**
-     * Enclosure
      * Enclosure character
      *
+     * This is useful for cell values that are either multi-line
+     * or contain the field delimiter character.
+     *
      * @var string
      */
     public $enclosure = '"';
 
     /**
-     * Enclose All
-     * Force enclosing all columns
+     * Force enclosing all columns.
+     *
+     * If false, only cells that are either multi-line or
+     * contain the field delimiter character are enclosed
+     * in the $enclosure char.
      *
      * @var bool
      */
     public $enclose_all = false;
 
     /**
-     * Conditions
      * Basic SQL-Like conditions for row matching
      *
      * @var string|null
@@ -125,7 +124,6 @@ class Csv {
     public $conditions = null;
 
     /**
-     * Offset
      * Number of rows to ignore from beginning of data. If present, the heading
      * row is also counted (if $this->heading == true). In other words,
      * $offset == 1 and $offset == 0 have the same meaning in that situation.
@@ -135,7 +133,6 @@ class Csv {
     public $offset = null;
 
     /**
-     * Limit
      * Limits the number of returned rows to the specified amount
      *
      * @var int|null
@@ -143,7 +140,6 @@ class Csv {
     public $limit = null;
 
     /**
-     * Auto Depth
      * Number of rows to analyze when attempting to auto-detect delimiter
      *
      * @var int
@@ -151,7 +147,6 @@ class Csv {
     public $auto_depth = 15;
 
     /**
-     * Auto Non Chars
      * Characters that should be ignored when attempting to auto-detect delimiter
      *
      * @var string
@@ -159,7 +154,6 @@ class Csv {
     public $auto_non_chars = "a-zA-Z0-9\n\r";
 
     /**
-     * Auto Preferred
      * preferred delimiter characters, only used when all filtering method
      * returns multiple possible delimiters (happens very rarely)
      *
@@ -168,15 +162,14 @@ class Csv {
     public $auto_preferred = ",;\t.:|";
 
     /**
-     * Convert Encoding
      * Should we convert the CSV character encoding?
+     * Used for both parse and unparse operations.
      *
      * @var bool
      */
     public $convert_encoding = false;
 
     /**
-     * Input Encoding
      * Set the input encoding
      *
      * @var string
@@ -184,7 +177,6 @@ class Csv {
     public $input_encoding = 'ISO-8859-1';
 
     /**
-     * Output Encoding
      * Set the output encoding
      *
      * @var string
@@ -202,15 +194,14 @@ class Csv {
     public $use_mb_convert_encoding = false;
 
     /**
-     * Linefeed
      * Line feed characters used by unparse, save, and output methods
+     * Popular choices are "\r\n" and "\n".
      *
      * @var string
      */
     public $linefeed = "\r";
 
     /**
-     * Output Delimiter
      * Sets the output delimiter used by the output method
      *
      * @var string
@@ -218,7 +209,6 @@ class Csv {
     public $output_delimiter = ',';
 
     /**
-     * Output filename
      * Sets the output filename
      *
      * @var string
@@ -226,7 +216,6 @@ class Csv {
     public $output_filename = 'data.csv';
 
     /**
-     * Keep File Data
      * keep raw file data in memory after successful parsing (useful for debugging)
      *
      * @var bool
@@ -270,7 +259,6 @@ class Csv {
     public $error = 0;
 
     /**
-     * Error Information
      * Detailed error information
      *
      * @var array
@@ -298,17 +286,16 @@ class Csv {
     public $titles = array();
 
     /**
-     * Data
-     * Two-dimensional array of CSV data
+     * Two-dimensional array of CSV data.
+     * The first dimension are the line numbers. Each line is represented as an array with field names as keys.
      *
-     * @var array
+     * @var array<array>
      */
     public $data = array();
 
     use DatatypeTrait;
 
     /**
-     * Constructor
      * Class constructor
      *
      * @param string|null $data            The CSV string or a direct file path.
@@ -368,7 +355,6 @@ class Csv {
     // ==============================================
 
     /**
-     * Parse
      * Parse a CSV file or string
      *
      * @param string|null $dataString  The CSV string or a direct file path
@@ -415,8 +401,7 @@ class Csv {
     }
 
     /**
-     * Save
-     * Save changes, or write a new file and/or data
+     * Save changes, or write a new file and/or data.
      *
      * @param string $file    File location to save to
      * @param array  $data    2D array of data
@@ -440,8 +425,9 @@ class Csv {
     }
 
     /**
-     * Output
-     * Generate a CSV based string for output.
+     * Generate a CSV-based string for output.
+     *
+     * Useful for exports in web applications.
      *
      * @param string|null $filename    If a filename is specified here or in the
      *                                 object, headers and data will be output
@@ -485,11 +471,15 @@ class Csv {
     }
 
     /**
-     * Encoding
      * Convert character encoding
      *
-     * @param string|null $input  Input character encoding, uses default if left blank
+     * Specify the encoding to use for the next parsing or unparsing.
+     * Calling this function will not change the data held in the object immediately.
+     *
+     * @param string|null $input  Input character encoding
+     *   If the value null is passed, the existing input encoding remains set (default: ISO-8859-1).
      * @param string|null $output Output character encoding, uses default if left blank
+     *   If the value null is passed, the existing input encoding remains set (default: ISO-8859-1).
      *
      * @return void
      */
@@ -505,8 +495,7 @@ class Csv {
     }
 
     /**
-     * Auto
-     * Auto-Detect Delimiter: Find delimiter by analyzing a specific number of
+     * Auto-detect delimiter: Find delimiter by analyzing a specific number of
      * rows to determine most probable delimiter character
      *
      * @param string|null $file          Local CSV file
@@ -609,7 +598,6 @@ class Csv {
     // ==============================================
 
     /**
-     * Parse File
      * Read file to string and call _parse_string()
      *
      * @param string|null $file  Path to a CSV file.
@@ -617,23 +605,26 @@ class Csv {
      *                           the path may also contain a protocol:
      *                           https://example.org/some/file.csv
      *
-     * @return array|bool
+     * @return array<array>|false
      */
     public function parseFile($file = null) {
         if (is_null($file)) {
             $file = $this->file;
         }
 
-        if (empty($this->file_data)) {
-            /**
-             * @see self::keep_file_data
-             * Usually, _parse_string will clean this
-             * Instead of leaving stale data for the next parseFile call behind.
-             */
-            $this->load_data($file);
+        /**
+         * @see self::keep_file_data
+         * Usually, _parse_string will clean this
+         * Instead of leaving stale data for the next parseFile call behind.
+         */
+        if (empty($this->file_data) && !$this->loadFile($file)) {
+            return false;
         }
 
-        return !empty($this->file_data) ? $this->_parse_string() : false;
+        if (empty($this->file_data)) {
+            return false;
+        }
+        return $this->data = $this->_parse_string();
     }
 
     /**
@@ -647,7 +638,8 @@ class Csv {
      *
      * @param string|null $data CSV data
      *
-     * @return array|false - 2D array with CSV data, or false on failure
+     * @return array<array>|false
+     *   2D array with CSV data, or false on failure
      */
     protected function _parse_string($data = null) {
         if (empty($data)) {
@@ -1234,14 +1226,14 @@ class Csv {
                 $file = $this->file;
             }
 
-            return $this->load_data($file);
+            return $this->loadFile($file);
         }
 
         return true;
     }
 
     /**
-     * Check if passed info might be delimiter
+     * Check if passed info might be delimiter.
      * Only used by find_delimiter
      *
      * @param string $char      Potential field separating character

tests/methods/ParseTest.php

@@ -166,18 +166,22 @@ class ParseTest extends TestCase {
 
         // This also tests if ::load_data removed the BOM from the data;
         // otherwise the 'title' column would have 3 extra bytes.
-        $this->assertEquals([
-            'title',
-            'isbn',
-            'publishedAt',
-        ], array_keys(reset($this->csv->data)));
+        $this->assertEquals(
+            [
+                'title',
+                'isbn',
+                'publishedAt',
+            ],
+            array_keys(reset($this->csv->data)));
 
         $titles = array_column($this->csv->data, 'title');
-        $this->assertEquals([
-            'Красивая кулинария',
-            'The Wine Connoisseurs',
-            'Weißwein',
-        ], $titles);
+        $this->assertEquals(
+            [
+                'Красивая кулинария',
+                'The Wine Connoisseurs',
+                'Weißwein',
+            ],
+            $titles);
     }
 
     public function testWithMultipleNewlines() {
@@ -185,18 +189,20 @@ class ParseTest extends TestCase {
         $aElse9 = array_column($this->csv->data, 'else9');
 
         /** @noinspection SpellCheckingInspection */
-        $this->assertEquals([
-            'Abweichung',
-            'Abweichung',
-            'Abweichung',
-            'Alt',
-            'Fehlt',
-            'Neu',
-            'OK',
-            'Fehlt',
-            'Fehlt',
-            'Fehlt',
-        ], $aElse9);
+        $this->assertEquals(
+            [
+                'Abweichung',
+                'Abweichung',
+                'Abweichung',
+                'Alt',
+                'Fehlt',
+                'Neu',
+                'OK',
+                'Fehlt',
+                'Fehlt',
+                'Fehlt',
+            ],
+            $aElse9);
     }
 
     /**
@@ -298,9 +304,9 @@ class ParseTest extends TestCase {
     /**
      * Call protected/private method of a class.
      *
-     * @param object $object     Instantiated object that we will run method on.
-     * @param string $methodName Method name to call
-     * @param array  $parameters Array of parameters to pass into method.
+     * @param object $object      Instantiated object that we will run method on.
+     * @param string $methodName  Method name to call
+     * @param array  $parameters  Array of parameters to pass into method.
      *
      * @return mixed Method return.
      */
@@ -331,4 +337,10 @@ class ParseTest extends TestCase {
         self::assertFalse($this->csv->parseFile(''));
         self::assertFalse($this->csv->parseFile(null));
     }
+
+    public function testParseFile() {
+        $data = $this->csv->parseFile(__DIR__ . '/fixtures/auto-double-enclosure.csv');
+        self::assertCount(2, $data);
+        self::assertEquals($data, $this->csv->data);
+    }
 }