Merge remote-tracking branch 'origin/master' into feat/sheet-context

# Conflicts:
#	README.md
#	tests/FastExcelTest.php

Author: elminson

README.md

@@ -65,6 +65,24 @@ Export only some attributes specifying columns names:
 });
 ```
 
+Hide columns from the exported file while still being able to use them inside the
+callback, using `hideColumnsPrefixedWith()`. This is handy for callback-only data
+(lookups, computed flags, etc.) that should not appear as a column:
+
+```php
+(new FastExcel(User::all()))->hideColumnsPrefixedWith()->export('users.csv', function ($user) {
+    return [
+        'Name'  => $user->name,
+        '_role' => $user->role, // used for logic below, never written to the file
+    ];
+});
+```
+
+Columns are hidden from both the header row and every data row. The prefix
+defaults to `_`, and any other one can be used — `hideColumnsPrefixedWith('tmp_')`.
+Hiding is opt-in: unless you call this method, every column is exported, so
+columns that already start with an underscore keep working as before.
+
 Download (from a controller method):
 
 ```php
@@ -166,6 +184,12 @@ You can also import a specific sheet by its number:
 $users = (new FastExcel)->sheet(3)->import('file.xlsx');
 ```
 
+`sheet()` also accepts a sheet name, so you can select a sheet without knowing its position:
+
+```php
+$users = (new FastExcel)->sheet('Users')->import('file.xlsx');
+```
+
 Import multiple sheets with sheets names:
 
 ```php
@@ -188,21 +212,46 @@ $sheets = (new FastExcel)
     });
 ```
 
-### Export large collections with chunk
+### Export large collections (low memory)
 
-Export rows one by one to avoid `memory_limit` issues [using `yield`](https://www.php.net/manual/en/language.generators.syntax.php):
+Passing a materialized collection (`User::all()`, `->get()`, `collect([...])`) loads every
+row into memory *before* the export starts, so it grows with the size of the data and a
+large enough dataset fails outright with `Allowed memory size of N bytes exhausted`. Feed a
+lazy source instead and peak memory stays flat, whatever the row count.
+
+Eloquent's `cursor()` (or `->lazy()`) returns a
+[`LazyCollection`](https://laravel.com/docs/collections#lazy-collections), which FastExcel
+streams row by row — no wrapper needed:
+
+```php
+// Export consumes only a few MB, even with 10M+ rows.
+(new FastExcel(User::cursor()))->export('users.xlsx');
+```
+
+For any other source, hand `export()` a generator [using `yield`](https://www.php.net/manual/en/language.generators.syntax.php):
 
 ```php
-function usersGenerator() {
-    foreach (User::cursor() as $user) {
-        yield $user;
+function rowsGenerator() {
+    foreach (some_paginated_source() as $row) {
+        yield $row;
     }
 }
 
-// Export consumes only a few MB, even with 10M+ rows.
-(new FastExcel(usersGenerator()))->export('test.xlsx');
+(new FastExcel(rowsGenerator()))->export('test.xlsx');
 ```
 
+Exporting 1,000,000 rows (4 columns) under a 512 MB `memory_limit`:
+
+| How you export | Peak memory | Result |
+| --- | --- | --- |
+| `export()` from a materialized collection | > 512 MB | **fails** once it exceeds `memory_limit` |
+| `export()` from a cursor / generator (streaming) | ~4 MB | always completes |
+
+Streaming does not change export *speed* (that is dominated by the underlying
+[OpenSpout](https://github.com/openspout/openspout) writer) — it is what keeps memory flat
+so very large files finish at all. `transpose()` cannot stream, as it must buffer the whole
+dataset to pivot rows and columns.
+
 ### Import large files (low memory)
 
 `import` returns a Collection containing every row, so memory grows with the size of

bench/bench.php

@@ -10,6 +10,13 @@
  * Reports the median wall-clock time and peak memory for the main
  * export/import paths. Memory numbers are stable across runs; time on
  * shared CI runners is noisy, so deltas under ~10% should be ignored.
+ *
+ * Peak memory is read with memory_get_peak_usage(false) — PHP's own
+ * allocator, which is released back between cases. The real (true) figure
+ * reports the process high-water mark from the OS allocator, which never
+ * shrinks, so a 4 MB streaming case measured after a 30 MB collection case
+ * would wrongly report ~30 MB. Using the PHP figure keeps every case honest
+ * in a single process.
  */
 
 use OpenSpout\Common\Entity\Style\Style;
@@ -29,29 +36,48 @@
 $dir = sys_get_temp_dir().'/fastexcel-bench-'.getmypid();
 mkdir($dir);
 
+$style = (new Style())->setFontBold();
+
+$results = [];
+
+// The collection cases share one materialized collection (15 MB+ at 30k rows).
+// It is freed before the streaming cases so their peak memory reflects the
+// streaming path alone, not a leftover collection still held in scope.
 $collection = collect(array_map(fn ($i) => [
     'id'     => $i,
     'name'   => 'name_'.$i,
     'email'  => 'user'.$i.'@example.com',
     'amount' => $i * 1.5,
 ], range(1, $rows)));
 
-$style = (new Style())->setFontBold();
-
-$results = [
-    'export_plain' => bench($runs, function () use ($collection, $dir) {
-        (new FastExcel($collection))->export($dir.'/plain.xlsx');
-    }),
-    'export_styled' => bench($runs, function () use ($collection, $dir, $style) {
-        (new FastExcel($collection))->headerStyle($style)->rowsStyle($style)->export($dir.'/styled.xlsx');
-    }),
-    'import' => bench($runs, function () use ($dir) {
-        (new FastExcel())->import($dir.'/plain.xlsx');
-    }),
-    'import_transposed' => bench($runs, function () use ($dir) {
-        (new FastExcel())->transpose()->import($dir.'/plain.xlsx');
-    }),
-];
+$results['export_plain'] = bench($runs, function () use ($collection, $dir) {
+    (new FastExcel($collection))->export($dir.'/plain.xlsx');
+});
+$results['export_styled'] = bench($runs, function () use ($collection, $dir, $style) {
+    (new FastExcel($collection))->headerStyle($style)->rowsStyle($style)->export($dir.'/styled.xlsx');
+});
+
+unset($collection);
+gc_collect_cycles();
+
+// Streaming export: a generator never materializes the full dataset, so peak
+// memory stays flat no matter how many rows are written.
+$results['export_generator'] = bench($runs, function () use ($rows, $dir) {
+    (new FastExcel(rowGenerator($rows)))->export($dir.'/gen.xlsx');
+});
+
+// Import cases read the file written by export_plain above.
+$results['import'] = bench($runs, function () use ($dir) {
+    (new FastExcel())->import($dir.'/plain.xlsx');
+});
+// Streaming import: importLazy() yields rows one at a time instead of
+// accumulating them into a Collection.
+$results['import_lazy'] = bench($runs, function () use ($dir) {
+    (new FastExcel())->importLazy($dir.'/plain.xlsx')->each(fn ($row) => $row);
+});
+$results['import_transposed'] = bench($runs, function () use ($dir) {
+    (new FastExcel())->transpose()->import($dir.'/plain.xlsx');
+});
 
 array_map('unlink', glob($dir.'/*'));
 rmdir($dir);
@@ -65,6 +91,22 @@
     }
 }
 
+/**
+ * A fresh generator over the benchmark row shape. Generators are single-use,
+ * so each timed run needs a new one.
+ */
+function rowGenerator(int $rows): Generator
+{
+    for ($i = 1; $i <= $rows; $i++) {
+        yield [
+            'id'     => $i,
+            'name'   => 'name_'.$i,
+            'email'  => 'user'.$i.'@example.com',
+            'amount' => $i * 1.5,
+        ];
+    }
+}
+
 function bench(int $runs, callable $callback): array
 {
     $times = [];
@@ -78,7 +120,7 @@ function bench(int $runs, callable $callback): array
         $start = hrtime(true);
         $callback();
         $times[] = (hrtime(true) - $start) / 1e9;
-        $peak = max($peak, memory_get_peak_usage(true));
+        $peak = max($peak, memory_get_peak_usage(false));
     }
 
     sort($times);

src/Exportable.php

@@ -39,13 +39,43 @@ trait Exportable
     /** @var array<string, string> */
     private $column_formats = [];
 
+    /** @var string|null */
+    private $hidden_column_prefix = null;
+
     /**
      * @param AbstractOptions $options
      *
      * @return mixed
      */
     abstract protected function setOptions(&$options);
 
+    /**
+     * Exclude columns whose key starts with the given prefix from the exported
+     * file (both the header row and every data row). This is opt-in: without
+     * calling it, every column is exported, so existing columns that happen to
+     * start with an underscore keep working as before.
+     *
+     * It is meant for callback-only data (lookups, computed flags, etc.) that
+     * you need inside the export callback but do not want in the output:
+     *
+     *     (new FastExcel($users))->hideColumnsPrefixedWith()->export('users.xlsx', fn ($user) => [
+     *         'Name'  => $user->name,
+     *         '_role' => $user->role, // used for logic, never written to the file
+     *     ]);
+     *
+     * Only string keys are considered, so positional/list rows are never
+     * affected. Column styles are matched against the remaining (visible)
+     * columns.
+     *
+     * @param string $prefix
+     */
+    public function hideColumnsPrefixedWith(string $prefix = '_'): static
+    {
+        $this->hidden_column_prefix = $prefix;
+
+        return $this;
+    }
+
     /** @param Style[] $styles */
     public function setHeaderColumnStyles($styles): static
     {
@@ -286,6 +316,8 @@ private function writeRowsFromCollection($writer, Collection $collection, ?calla
                 $values = $values->toArray();
             }
 
+            $values = $this->removeHiddenColumns($values);
+
             if ($use_styles) {
                 // Column styles are matched against the value keys; use positional
                 // keys so numeric style indexes work with associative rows.
@@ -309,6 +341,7 @@ private function writeRowsFromGenerator($writer, Traversable $generator, ?callab
 
             // Prepare row (i.e remove non-string)
             $item = $this->transformRow($item);
+            $item = $this->removeHiddenColumns($item);
 
             // Add header row.
             if ($this->with_header && $key === 0) {
@@ -343,10 +376,37 @@ private function writeHeader($writer, $first_row)
             return;
         }
 
-        $keys = array_keys(is_array($first_row) ? $first_row : $first_row->toArray());
+        $row = is_array($first_row) ? $first_row : $first_row->toArray();
+        $keys = array_keys($this->removeHiddenColumns($row));
         $writer->addRow($this->createRow($keys, $this->header_style, $this->header_column_styles));
     }
 
+    /**
+     * Remove "hidden" columns from a row before it is written. Does nothing
+     * unless hideColumnsPrefixedWith() has been called, so exports are
+     * unchanged by default. Because the header is derived from the first row's
+     * keys, hidden columns are dropped from the header automatically as well.
+     *
+     * Numeric keys are always kept, so positional/list rows are left untouched.
+     *
+     * @param array $row
+     *
+     * @return array
+     */
+    private function removeHiddenColumns(array $row): array
+    {
+        $prefix = $this->hidden_column_prefix;
+        if ($prefix === null || $prefix === '') {
+            return $row;
+        }
+
+        return array_filter(
+            $row,
+            static fn ($key) => !is_string($key) || !str_starts_with($key, $prefix),
+            ARRAY_FILTER_USE_KEY
+        );
+    }
+
     /**
      * Prepare collection by removing non string if required.
      */

src/Facades/FastExcel.php

@@ -12,6 +12,7 @@
  * @method static string                           export($path, callable $callback = null)
  * @method static \Illuminate\Support\Collection   importSheets($path, callable $callback = null)
  * @method static \Rap2hpoutre\FastExcel\FastExcel limitRows(?int $rows = null)
+ * @method static \Rap2hpoutre\FastExcel\FastExcel hideColumnsPrefixedWith($prefix = '_')
  * @method static \Rap2hpoutre\FastExcel\FastExcel configureCsv($delimiter = ',', $enclosure = '"', $encoding = 'UTF-8', $bom = false)
  * @method static \Rap2hpoutre\FastExcel\FastExcel configureReaderUsing(?callable $callback = null)
  * @method static \Rap2hpoutre\FastExcel\FastExcel configureWriterUsing(?callable $callback = null)

src/FastExcel.php

@@ -91,7 +91,7 @@ public function data($data)
     }
 
     /**
-     * @param $sheet_number
+     * @param int|string $sheet_number 1-based index or sheet name
      *
      * @return $this
      */

src/Importable.php

@@ -19,7 +19,7 @@
 trait Importable
 {
     /**
-     * @var int
+     * @var int|string
      */
     private $sheet_number = 1;
 
@@ -50,7 +50,7 @@ public function import($path, ?callable $callback = null)
         $reader = $this->reader($path);
 
         foreach ($reader->getSheetIterator() as $key => $sheet) {
-            if ($this->sheet_number == $key) {
+            if ($this->sheetMatches($key, $sheet)) {
                 $collection = $this->importSheet($sheet, $callback);
                 break;
             }
@@ -79,7 +79,7 @@ public function importLazy($path, ?callable $callback = null)
 
             try {
                 foreach ($reader->getSheetIterator() as $key => $sheet) {
-                    if ($this->sheet_number != $key) {
+                    if (!$this->sheetMatches($key, $sheet)) {
                         continue;
                     }
                     if ($this->transpose) {
@@ -96,6 +96,24 @@ public function importLazy($path, ?callable $callback = null)
         });
     }
 
+    /**
+     * Whether the given sheet is the one selected via sheet().
+     * Selection accepts a 1-based index (int) or a sheet name (string).
+     *
+     * @param int            $key
+     * @param SheetInterface $sheet
+     *
+     * @return bool
+     */
+    private function sheetMatches(int $key, SheetInterface $sheet): bool
+    {
+        if (is_string($this->sheet_number)) {
+            return $this->sheet_number === $sheet->getName();
+        }
+
+        return (int) $this->sheet_number === $key;
+    }
+
     /**
      * @param string|\Symfony\Component\HttpFoundation\File\UploadedFile $path
      * @param callable|null                                              $callback