Add trimValues() and formatValuesUsing() to the reader (#195)

* @
Add trimValues() and formatValuesUsing() to the reader

The reader could already clean up header names (trimHeaderRow,
headersToSnakeCase, formatHeadersUsing) but had no equivalent for the
actual cell values. This adds two symmetric reader methods:

- trimValues(?string $characters = null)
- formatValuesUsing(callable $callback)  // receives ($value, $key)

Non-string values (e.g. dates) are left untouched by trimValues().
Formatting runs per-row inside the LazyCollection, preserving the
package low memory usage. Includes tests and README docs.
@

* Strengthen no-header-row trim test to assert trimming on whitespace rows

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Freek Van der Herten <freek@spatie.be>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

README.md

@@ -260,6 +260,46 @@ $rows = SimpleExcelReader::create($pathToCsv)
     });
 ```
 
+#### Trimming and formatting values
+
+Just like you can clean up header names, you can clean up the data values themselves. This is handy when importing files where cells contain stray whitespace or need to be normalized.
+
+Use `trimValues()` to strip whitespace from every value.
+
+```csv
+email,first_name
+  john@example.com  ,  john
+jane@example.com,jane
+```
+
+```php
+$rows = SimpleExcelReader::create($pathToCsv)
+    ->trimValues()
+    ->getRows()
+    ->each(function(array $rowProperties) {
+       // in the first pass $rowProperties will contain
+       // ['email' => 'john@example.com', 'first_name' => 'john']
+    });
+```
+
+Like `trim`, `trimValues()` accepts an optional argument specifying which characters to trim. This argument is a *set of characters* stripped from both ends of each value (exactly like PHP's [`trim`](https://www.php.net/manual/en/function.trim.php)), **not** a suffix. For example, `trimValues('*')` removes any leading or trailing `*` from every value. Be careful with letters: `trimValues('.com')` would also turn `Tom` into `T`.
+
+```php
+$rows = SimpleExcelReader::create($pathToCsv)
+    ->trimValues('*')
+    ->getRows();
+```
+
+For full control, use `formatValuesUsing()` and pass a closure. The closure receives the value and its header key, so you can normalize values per column. Non-string values (such as dates read from an Excel file) are passed through untouched by `trimValues()`, but your own closure is responsible for handling them.
+
+```php
+$rows = SimpleExcelReader::create($pathToCsv)
+    ->formatValuesUsing(function ($value, $key) {
+        return $key === 'email' ? strtolower($value) : $value;
+    })
+    ->getRows();
+```
+
 #### Manually working with the reader object
 
 Under the hood this package uses the [openspout/spout](https://github.com/openspout/openspout) package. You can get to the underlying reader that implements `\OpenSpout\Reader\ReaderInterface` by calling the `getReader` method.

src/SimpleExcelReader.php

@@ -26,6 +26,9 @@ class SimpleExcelReader
     protected bool $trimHeader = false;
     protected bool $headersToSnakeCase = false;
     protected bool $parseFormulas = true;
+    protected bool $trimValues = false;
+    protected ?string $trimValueCharacters = null;
+    protected mixed $formatValuesUsing = null;
     protected ?string $trimHeaderCharacters = null;
     protected mixed $formatHeadersUsing = null;
     protected ?array $headers = null;
@@ -160,6 +163,21 @@ public function headersToSnakeCase(): self
         return $this;
     }
 
+    public function trimValues(?string $characters = null): self
+    {
+        $this->trimValues = true;
+        $this->trimValueCharacters = $characters;
+
+        return $this;
+    }
+
+    public function formatValuesUsing(callable $callback): self
+    {
+        $this->formatValuesUsing = $callback;
+
+        return $this;
+    }
+
     public function keepFormulas()
     {
         $this->parseFormulas = false;
@@ -376,7 +394,7 @@ protected function getValueFromRow(Row $row): array
         $headers = $this->customHeaders ?: $this->headers;
 
         if (! $headers) {
-            return $values;
+            return $this->processValues($values);
         }
 
         $values = array_slice($values, 0, count($headers));
@@ -385,7 +403,33 @@ protected function getValueFromRow(Row $row): array
             $values[] = '';
         }
 
-        return array_combine($headers, $values);
+        return $this->processValues(array_combine($headers, $values));
+    }
+
+    protected function processValues(array $values): array
+    {
+        if ($this->trimValues) {
+            $values = array_map([$this, 'trimValue'], $values);
+        }
+
+        if ($this->formatValuesUsing) {
+            $keys = array_keys($values);
+            $formatted = array_map($this->formatValuesUsing, array_values($values), $keys);
+            $values = array_combine($keys, $formatted);
+        }
+
+        return $values;
+    }
+
+    protected function trimValue(mixed $value): mixed
+    {
+        if (! is_string($value)) {
+            return $value;
+        }
+
+        return is_null($this->trimValueCharacters)
+            ? trim($value)
+            : trim($value, $this->trimValueCharacters);
     }
 
     protected function getSheet(): SheetInterface

tests/SimpleExcelReaderTest.php

@@ -496,6 +496,103 @@ function () {
     ]);
 });
 
+it('can trim whitespace from values', function () {
+    $rows = SimpleExcelReader::create(getStubPath('values-with-spaces.csv'))
+        ->trimValues()
+        ->getRows()
+        ->toArray();
+
+    expect($rows)->toEqual([
+        [
+            'email' => 'john@example.com',
+            'first_name' => 'john',
+            'last_name' => 'doe',
+        ],
+        [
+            'email' => 'mary-jane@example.com',
+            'first_name' => 'mary jane',
+            'last_name' => 'doe',
+        ],
+    ]);
+});
+
+it('can trim values with custom characters', function () {
+    $rows = SimpleExcelReader::create(getStubPath('padded-values.csv'))
+        ->trimValues('*')
+        ->getRows()
+        ->first();
+
+    expect($rows)->toEqual([
+        'email' => 'john@example.com',
+        'first_name' => 'john',
+    ]);
+});
+
+it('can format values using a callback', function () {
+    $rows = SimpleExcelReader::create(getStubPath('header-and-rows.csv'))
+        ->formatValuesUsing(fn ($value) => strtoupper($value))
+        ->getRows()
+        ->first();
+
+    expect($rows)->toEqual([
+        'email' => 'JOHN@EXAMPLE.COM',
+        'first_name' => 'JOHN',
+        'last_name' => 'DOE',
+    ]);
+});
+
+it('passes the header key to the value formatter', function () {
+    $rows = SimpleExcelReader::create(getStubPath('header-and-rows.csv'))
+        ->formatValuesUsing(fn ($value, $key) => $key === 'email' ? strtoupper($value) : $value)
+        ->getRows()
+        ->first();
+
+    expect($rows)->toEqual([
+        'email' => 'JOHN@EXAMPLE.COM',
+        'first_name' => 'john',
+        'last_name' => 'doe',
+    ]);
+});
+
+it('can trim and format values together', function () {
+    $rows = SimpleExcelReader::create(getStubPath('values-with-spaces.csv'))
+        ->trimValues()
+        ->formatValuesUsing(fn ($value) => strtoupper($value))
+        ->getRows()
+        ->first();
+
+    expect($rows)->toEqual([
+        'email' => 'JOHN@EXAMPLE.COM',
+        'first_name' => 'JOHN',
+        'last_name' => 'DOE',
+    ]);
+});
+
+it('can format values when there is no header row', function () {
+    $rows = SimpleExcelReader::create(getStubPath('values-with-spaces.csv'))
+        ->noHeaderRow()
+        ->trimValues()
+        ->getRows()
+        ->toArray();
+
+    expect($rows)->toEqual([
+        ['email', 'first_name', 'last_name'],
+        ['john@example.com', 'john', 'doe'],
+        ['mary-jane@example.com', 'mary jane', 'doe'],
+    ]);
+});
+
+it('does not trim non-string values', function () {
+    $dates = SimpleExcelReader::create(getStubPath('formatted_dates.xlsx'))
+        ->trimValues()
+        ->getRows()
+        ->pluck('created_at')
+        ->toArray();
+
+    expect($dates[0])->toBeInstanceOf(DateTimeImmutable::class);
+    expect($dates[1])->toBeInstanceOf(DateTimeImmutable::class);
+});
+
 it('can retrieve rows with a different delimiter', function () {
     $rows = SimpleExcelReader::create(getStubPath('header-and-rows-other-delimiter.csv'))
         ->useDelimiter(';')

tests/stubs/padded-values.csv

@@ -0,0 +1,2 @@
+email,first_name
+*john@example.com*,*john*

tests/stubs/values-with-spaces.csv

@@ -0,0 +1,3 @@
+email,first_name,last_name
+  john@example.com  ,  john,doe
+mary-jane@example.com,mary jane  ,  doe