feature: excel adapter loader

Author: norberttech

documentation/components/adapters/excel.md

@@ -1,4 +1,4 @@
-# Excel Adapter 
+# Excel Adapter
 
 - [⬅️️ Back](/documentation/introduction.md)
 - [📦Packagist](https://packagist.org/packages/flow-php/etl-adapter-excel)
@@ -20,6 +20,9 @@ developers dealing with Excel in large-scale and data-intensive projects. With F
 managing Excel data within your ETL workflows becomes a more simplified and efficient task, perfectly aligning
 with the robust and adaptable nature of the Flow PHP ecosystem.
 
+> **Note:** This adapter only supports local filesystem paths due to limitations of the underlying OpenSpout library.
+> Remote filesystems (S3, Azure Blob Storage, etc.) are not supported.
+
 ## Installation
 
 ``` 
@@ -66,3 +69,138 @@ $rows = data_frame()
     )
     ->fetch();
 ```
+
+## Loader
+
+### Basic Usage
+
+```php
+<?php
+
+data_frame()
+    ->read($extractor)
+    ->write(to_excel('path/to/output.xlsx'))
+    ->run();
+```
+
+### ODS Format
+
+```php
+<?php
+
+use Flow\ETL\Adapter\Excel\ExcelWriter;
+
+data_frame()
+    ->read($extractor)
+    ->write(to_excel('path/to/output.ods')->withWriter(ExcelWriter::ODS))
+    ->run();
+```
+
+### Custom Sheet Name
+
+```php
+<?php
+
+data_frame()
+    ->read($extractor)
+    ->write(to_excel('path/to/output.xlsx')->withSheetName('MyData'))
+    ->run();
+```
+
+### Dynamic Sheet Names from Entry
+
+Route rows to different sheets based on entry values:
+
+```php
+<?php
+
+$loader = to_excel('path/to/output.xlsx')
+    ->withSheetNameFromEntry('category');
+
+data_frame()
+    ->read($extractor)
+    ->write($loader)
+    ->run();
+```
+
+### Without Header Row
+
+```php
+<?php
+
+data_frame()
+    ->read($extractor)
+    ->write(to_excel('path/to/output.xlsx')->withHeader(false))
+    ->run();
+```
+
+### Header Styling
+
+```php
+<?php
+
+use OpenSpout\Common\Entity\Style\Style;
+
+$headerStyle = new Style(fontBold: true);
+
+$loader = to_excel('path/to/output.xlsx')
+    ->withHeaderStyle($headerStyle);
+
+data_frame()
+    ->read($extractor)
+    ->write($loader)
+    ->run();
+```
+
+### Cell Styling
+
+Apply custom styles to individual cells based on entry values:
+
+```php
+<?php
+
+use Flow\ETL\Adapter\Excel\CellStyler;
+use Flow\ETL\Row\Entry;
+use OpenSpout\Common\Entity\Style\Style;
+
+$cellStyler = new class implements CellStyler {
+    public function style(Entry $entry, int $rowNumber, int $columnIndex, string $sheetName): ?Style
+    {
+        // Make first column bold
+        if ($columnIndex === 0) {
+            return new Style(fontBold: true);
+        }
+
+        return null;
+    }
+};
+
+$loader = to_excel('path/to/output.xlsx')
+    ->withCellStyler($cellStyler);
+
+data_frame()
+    ->read($extractor)
+    ->write($loader)
+    ->run();
+```
+
+### Custom Writer Options
+
+For advanced configuration, pass OpenSpout options directly:
+
+```php
+<?php
+
+use OpenSpout\Writer\XLSX\Options as XlsxOptions;
+
+$options = new XlsxOptions(
+    SHOULD_USE_INLINE_STRINGS: false,
+    DEFAULT_COLUMN_WIDTH: 15.0,
+    DEFAULT_ROW_HEIGHT: 20.0,
+);
+
+data_frame()
+    ->read($extractor)
+    ->write(to_excel('path/to/output.xlsx')->withWriterOptions($options))
+    ->run();
+```

src/adapter/etl-adapter-excel/src/Flow/ETL/Adapter/Excel/CellStyler.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Flow\ETL\Adapter\Excel;
+
+use Flow\ETL\Row\Entry;
+use OpenSpout\Common\Entity\Style\Style;
+
+interface CellStyler
+{
+    /**
+     * Return a Style for the given cell, or null for default styling.
+     *
+     * @param Entry<mixed> $entry the entry being written
+     * @param int $rowNumber the 1-based row number in the sheet (1 = first data row, not header)
+     * @param int $columnIndex the 0-based column index
+     * @param string $sheetName the name of the sheet being written to
+     */
+    public function style(Entry $entry, int $rowNumber, int $columnIndex, string $sheetName) : ?Style;
+}

src/adapter/etl-adapter-excel/src/Flow/ETL/Adapter/Excel/DSL/functions.php

@@ -6,6 +6,7 @@
 
 use function Flow\Filesystem\DSL\path_real;
 use Flow\ETL\{Adapter\Excel\ExcelExtractor,
+    Adapter\Excel\ExcelLoader,
     Adapter\Excel\Function\IsValidExcelSheetName,
     Attribute\DocumentationDSL,
     Attribute\DocumentationExample,
@@ -22,6 +23,13 @@ function from_excel(
     return new ExcelExtractor(\is_string($path) ? path_real($path) : $path);
 }
 
+#[DocumentationDSL(module: Module::EXCEL, type: DSLType::LOADER)]
+#[DocumentationExample(topic: 'data_frame', example: 'data_writing', option: 'excel')]
+function to_excel(string|Path $path) : ExcelLoader
+{
+    return new ExcelLoader(\is_string($path) ? path_real($path) : $path);
+}
+
 #[DocumentationDSL(module: Module::EXCEL, type: DSLType::HELPER)]
 function is_valid_excel_sheet_name(string|ScalarFunction $sheet_name) : IsValidExcelSheetName
 {