## Getting Started

### Minimal Setup
1. **Installation**
   ```bash
   composer require box/spout

Spout is dependency-free and requires PHP 7.2+. Note: v3.3.0 introduces performance improvements for ODS/XLSX and fixes locale-dependent float handling.

First Use Case: Reading a CSV (Unchanged)

use Box\Spout\Reader\Common\Creator\ReaderEntityFactory;
use Box\Spout\Reader\CSV\Reader;

$reader = ReaderEntityFactory::createCSVReader();
$reader->open('path/to/file.csv');

foreach ($reader->getSheetIterator() as $sheet) {
    foreach ($sheet->getRowIterator() as $row) {
        $cells = $row->getCells();
        // Process cells (e.g., $cells[0]->getValue())
    }
}
$reader->close();

First Use Case: Writing an XLSX (Updated for v3.3.0)

use Box\Spout\Writer\Common\Creator\WriterEntityFactory;
use Box\Spout\Writer\XLSX\Writer;

$writer = WriterEntityFactory::createXLSXWriter();
$writer->openToFile('path/to/output.xlsx');

// v3.3.0: Supports strict OOXML and inline strings with multiple nodes
$writer->addSheet('Sheet1');
$writer->getSheet()->addRow(['Header1', 'Header2', 3.14159]); // Floats now locale-independent
$writer->getSheet()->addRow([1, 2]);

// Apply styling (performance improved in v3.3.0)
$writer->getSheet()->getStyleCell('A1')->applyFromArray([
    'font' => ['bold' => true],
]);

$writer->close();

First Use Case: Reading/Writing ODS (New Performance Focus)

// ODS Reader (Performance improved in v3.3.0)
$reader = ReaderEntityFactory::createODSReader();
$reader->open('file.ods');

// ODS Writer (Performance improved in v3.3.0)
$writer = WriterEntityFactory::createODSWriter();
$writer->openToFile('output.ods');

Where to Look First

Spout Documentation (Archived but still relevant)
src/Box/Spout/Reader/ and src/Box/Spout/Writer/ for core classes.
tests/ for edge-case examples (e.g., large files, special characters).
Release Notes for v3.3.0: Focus on ODS/XLSX performance and strict OOXML support.

Implementation Patterns

Common Workflows

1. Bulk Data Import/Export (Unchanged)

Pattern: Use Spout for large datasets (e.g., CSV imports for Laravel Eloquent).

$reader = ReaderEntityFactory::createCSVReader();
$reader->open('users.csv');

foreach ($reader->getSheetIterator() as $sheet) {
    foreach ($sheet->getRowIterator() as $row) {
        $user = new User();
        $user->name = $row->getCell(0)->getValue();
        $user->email = $row->getCell(1)->getValue();
        $user->save();
    }
}

2. Streaming Large Files (Updated for v3.3.0)

Pattern: Process rows one-by-one to avoid memory issues. Note: ODS/XLSX performance is now optimized for large files.

$reader->open('huge_file.xlsx'); // ODS/XLSX now faster
foreach ($reader->getSheetIterator() as $sheet) {
    foreach ($sheet->getRowIterator() as $row) {
        processRow($row); // Fire-and-forget or queue
    }
}

3. Dynamic Sheet/Row Handling (Updated for Headers RFC6266)

Pattern: Skip headers, validate data, or transform on-the-fly.

$reader->open('data.csv');
$reader->setShouldSkipEmptyRows(false);
$reader->setFields([
    'name' => 'col1',
    'age' => 'col2',
]);
// Note: Headers now follow RFC6266 (v3.3.0)

4. Writing with Styling (Performance Improved in v3.3.0)

Pattern: Apply formatting (bold, colors) to XLSX/ODS. Note: Styling performance is now optimized.

$writer->openToBrowser('report.xlsx');
$writer->getSheet()->getStyleCell('A1')->applyFromArray([
    'font' => ['bold' => true, 'size' => 14],
    'alignment' => ['horizontal' => 'center'],
]);

5. Integration with Laravel (Unchanged)

Pattern: Use Spout in Laravel commands, jobs, or API responses.

// Example: Export users to XLSX in a command (v3.3.0 OOXML support)
public function handle() {
    $writer = WriterEntityFactory::createXLSXWriter();
    $writer->openToBrowser('users.xlsx');
    $writer->addSheet('Users');
    foreach (User::all() as $user) {
        $writer->getSheet()->addRow([$user->name, $user->email, $user->created_at]);
    }
    $writer->close();
}

Integration Tips

Laravel-Specific

Queue Jobs: Offload large exports to queues to avoid timeouts.

dispatch(new ExportUsersJob('users.xlsx')); // Leverage v3.3.0 ODS/XLSX performance

Storage Disk: Use Laravel’s storage_path() for file paths.

$writer->openToFile(storage_path('app/exports/report.xlsx'));

Validation: Combine with Laravel Validation for data integrity.

$rowData = $row->getCells();
$validated = Validator::make($rowData, [
    'email' => 'required|email',
]);

Performance (Updated for v3.3.0)

Batch Processing: Process 1000 rows at a time for memory efficiency. Note: ODS/XLSX are now faster.
Streaming: Use openToBrowser() for direct downloads without temp files.

Chunking: For reads, use getRowIterator() with chunking:

$rows = iterator_to_array($sheet->getRowIterator(), false);
array_chunk($rows, 1000); // Process in chunks (ODS/XLSX now optimized)

Strict OOXML: For XLSX, enable strict mode for compliance:
```
$writer->setStrictOOXML(true); // New in v3.3.0
```

Testing (Unchanged)

Mock Spout: Use Box\Spout\Common\Entity\IO\Type to mock readers/writers in tests.
Temp Files: Use Laravel’s Storage::fake() for testing file outputs.

Gotchas and Tips

Pitfalls

Memory Leaks (Unchanged)
- Issue: Forgetting to call $reader->close() or $writer->close() can leak resources.
- Fix: Use __destruct() or wrap in a try-finally block.
```
try {
    $reader->open('file.csv');
    // Process...
} finally {
    $reader->close();
}
```
Encoding Issues (Unchanged)
- Issue: CSV files with special characters (e.g., UTF-8) may corrupt.
- Fix: Explicitly set encoding:
```
$reader->setEncoding('UTF-8');
```
Large File Timeouts (Updated for v3.3.0)
- Issue: Processing giant files (e.g., 1GB+) may hit PHP timeouts.
- Fix: Use setTimeout() or offload to a queue/CLI. Note: ODS/XLSX performance is now improved.
- Pro Tip: For XLSX, use setStrictOOXML(true) for better handling of edge cases.
Sheet Limits (Unchanged)
- Issue: XLSX/ODS has row/column limits (~1M rows per sheet).
- Fix: Split data across multiple sheets or use CSV for huge datasets.
Case Sensitivity (Unchanged)
- Issue: Field names in setFields() are case-sensitive.

Spout Laravel Package