Merge 0233f9c into 6a3d0e6

CHANGELOG.md

@@ -6,7 +6,10 @@ All Notable changes to `Csv` will be documented in this file
 
 ### Added
 
-- Nothing
+- Support for disabling/enabling BOM stripping via adding:
+    - `AbstractCsv::enableBOMSkipping`
+    - `AbstractCsv::disableBOMSkipping`
+    - `AbstractCsv::isBOMSkippingEnabled`
 
 ### Deprecated
 

composer.json

@@ -60,6 +60,14 @@
             "@phpunit"
         ]
     },
+    "scripts-descriptions": {
+        "phpcs": "Runs coding style test suite",
+        "phpstan": "Runs complete codebase static analysis",
+        "phpstan-src": "Runs source code static analysis",
+        "phpstan-test": "Runs test suite static analysis",
+        "phpunit": "Runs unit and functional testing",
+        "test": "Runs full test suite"
+    },
     "suggest": {
         "ext-iconv" : "Needed to ease transcoding CSV using iconv stream filters"
     },

docs/9.0/connections/bom.md

@@ -76,3 +76,35 @@ $bom = $csv->getOutputBOM(); //returns "\xEF\xBB\xBF"
 <p class="message-info">The default output <code>BOM</code> character is set to an empty string.</p>
 <p class="message-warning">The output BOM sequence is <strong>never</strong> saved to the CSV document.</p>
 
+### Controlling BOM sequence skipping
+
+<p class="message-info">Since version <code>9.4.0</code>.</p>
+
+~~~php
+AbstractCsv::enableBOMSkipping(): self;
+AbstractCsv::disableBOMSkipping(): self;
+AbstractCsv::isBOMSkippingEnabled(): bool;
+~~~
+
+- `enableBOMSkipping`: enables skipping the input BOM from your CSV document.
+- `disableBOMSkipping`: disables skipping the input BOM from your CSV document.
+- `isBOMSkippingEnabled`: tells whether skipping the input BOM will be done.
+
+<p class="message-notice">By default and to avoid BC Break, BOM skipping is enabled.</p>
+
+If your document does not contains any BOM sequence you can speed up the CSV iterator by removing the step that ensure the BOM sequence if present is skipped.
+
+~~~php
+$raw_csv = Reader::BOM_UTF8."john,doe,john.doe@example.com\njane,doe,jane.doe@example.com\n";
+$csv = Reader::createFromString($raw_csv);
+$csv->setOutputBOM(Reader::BOM_UTF16_BE);
+$csv->disableBOMSkipping();
+ob_start();
+$csv->output();
+$document = ob_get_clean();
+~~~
+
+the returned `$document` will contains **2** BOM marker instead of one.
+
+<p class="message-warning">If you are using a <code>stream</code> that can not be seekable you should disabled BOM skipping otherwise an <code>Exception</code> will be triggered.</p>
+<p class="message-warning">The BOM sequence is never removed from the CSV document, it is only skipped from the result set.</p>

src/AbstractCsv.php

@@ -88,6 +88,13 @@ abstract class AbstractCsv implements ByteSequence
      */
     protected $document;
 
+    /**
+     * Tells whether the BOM must be stripped.
+     *
+     * @var bool
+     */
+    protected $is_BOM_skipping_enabled = true;
+
     /**
      * New instance.
      *
@@ -247,6 +254,14 @@ public function hasStreamFilter(string $filtername): bool
         return $this->stream_filters[$filtername] ?? false;
     }
 
+    /**
+     * Tells whether the BOM can be stripped if presents.
+     */
+    public function isBOMSkippingEnabled(): bool
+    {
+        return $this->is_BOM_skipping_enabled;
+    }
+
     /**
      * Retuns the CSV document as a Generator of string chunk.
      *
@@ -310,9 +325,12 @@ public function output(string $filename = null): int
         if (null !== $filename) {
             $this->sendHeaders($filename);
         }
-        $input_bom = $this->getInputBOM();
+
         $this->document->rewind();
-        $this->document->fseek(strlen($input_bom));
+        if ($this->is_BOM_skipping_enabled) {
+            $this->document->fseek(strlen($this->getInputBOM()));
+        }
+
         echo $this->output_bom;
 
         return strlen($this->output_bom) + $this->document->fpassthru();
@@ -420,6 +438,30 @@ public function setEscape(string $escape): self
         throw new Exception(sprintf('%s() expects escape to be a single character or the empty string %s given', __METHOD__, $escape));
     }
 
+    /**
+     * Enables BOM Stripping.
+     *
+     * @return static
+     */
+    public function enableBOMSkipping(): self
+    {
+        $this->is_BOM_skipping_enabled = true;
+
+        return $this;
+    }
+
+    /**
+     * Disables BOM Stripping.
+     *
+     * @return static
+     */
+    public function disableBOMSkipping(): self
+    {
+        $this->is_BOM_skipping_enabled = false;
+
+        return $this;
+    }
+
     /**
      * Sets the BOM sequence to prepend the CSV on output.
      *

src/Reader.php

@@ -266,9 +266,13 @@ public function getRecords(array $header = []): Iterator
         $normalized = static function ($record): bool {
             return is_array($record) && $record != [null];
         };
-        $bom = $this->getInputBOM();
-        $document = $this->getDocument();
 
+        $bom = '';
+        if ($this->is_BOM_skipping_enabled) {
+            $bom = $this->getInputBOM();
+        }
+
+        $document = $this->getDocument();
         $records = $this->stripBOM(new CallbackFilterIterator($document, $normalized), $bom);
         if (null !== $this->header_offset) {
             $records = new CallbackFilterIterator($records, function (array $record, int $offset): bool {

tests/CsvTest.php

@@ -21,6 +21,8 @@
 use function function_exists;
 use function iterator_to_array;
 use function League\Csv\is_iterable as CSVIsiterable;
+use function ob_get_clean;
+use function ob_start;
 use function strtolower;
 use function tmpfile;
 use function unlink;
@@ -457,4 +459,43 @@ public function testGetPathnameWithTempFile()
         self::assertSame('php://temp', Writer::createFromString(new SplTempFileObject())->getPathname());
         self::assertSame('php://temp', Writer::createFromFileObject(new SplTempFileObject())->getPathname());
     }
+
+    /**
+     * @covers ::isBOMSkippingEnabled
+     * @covers ::disableBOMSkipping
+     * @covers ::enableBOMSkipping
+     */
+    public function testBOMStripping()
+    {
+        $reader = Reader::createFromString();
+        self::assertTrue($reader->isBOMSkippingEnabled());
+        $reader->disableBOMSkipping();
+        self::assertFalse($reader->isBOMSkippingEnabled());
+        $reader->enableBOMSkipping();
+        self::assertTrue($reader->isBOMSkippingEnabled());
+    }
+
+    /**
+     * @runInSeparateProcess
+     * @covers ::output
+     */
+    public function testOutputDoesNotStripBOM()
+    {
+        $raw_csv = Reader::BOM_UTF8."john,doe,john.doe@example.com\njane,doe,jane.doe@example.com\n";
+        $csv = Reader::createFromString($raw_csv);
+        $csv->setOutputBOM(Reader::BOM_UTF16_BE);
+        ob_start();
+        $csv->output();
+        $result = ob_get_clean();
+        self::assertNotContains(Reader::BOM_UTF8, $result);
+        self::assertContains(Reader::BOM_UTF16_BE, $result);
+
+        $csv->disableBOMSkipping();
+        ob_start();
+        $csv->output();
+        $result = ob_get_clean();
+        self::assertContains(Reader::BOM_UTF16_BE, $result);
+        self::assertContains(Reader::BOM_UTF8, $result);
+        self::assertTrue(0 === strpos($result, Reader::BOM_UTF16_BE.Reader::BOM_UTF8));
+    }
 }

tests/ReaderTest.php

@@ -328,6 +328,22 @@ public function testStripNoBOM()
         }
     }
 
+    public function testDisablingBOMStripping()
+    {
+        $expected_record = [Reader::BOM_UTF16_LE.'john', 'doe', 'john.doe@example.com'];
+        $fp = fopen('php://temp', 'r+');
+        fputcsv($fp, $expected_record);
+        $csv = Reader::createFromStream($fp);
+        $csv->disableBOMSkipping();
+        self::assertSame(Reader::BOM_UTF16_LE, $csv->getInputBOM());
+        foreach ($csv as $offset => $record) {
+            self::assertSame($expected_record, $record);
+        }
+        $csv = null;
+        fclose($fp);
+        $fp = null;
+    }
+
     /**
      * @covers ::getIterator
      * @dataProvider appliedFlagsProvider