Skip to content
PHP 8.1+ Open source Developer documentation
Tools Packagist
Docs v2.0.6
Documentation versions v2.0.6Current v2.0.5Maintenance v2.0.4Maintenance v2.0.3Maintenance v2.0.0Initial v2 Compare versions →
MNB PHPExcelDeveloper Guide
AI

Core concepts

Normal vs Streaming Reads

Choose the correct read mode for memory, random access, metadata, and throughput.

Level
Intermediate
Reading time
9 min
Package
mnb/mnb-phpexcel
Updated
ReadSession::normal()ReadSession::streaming()ReadSession::rows()ReadSession::chunks()
Choose by access pattern

Normal for rich access. Streaming for forward-only row work.

File extension is not the deciding factor. Choose the mode from what the application must retain, revisit, or process incrementally.

Normal mode

Keep workbook convenience available.

Use normal mode when the application needs random cell access or richer workbook structures such as styles, images, and metadata.

normal()cell()cellStyle()images()
Streaming mode

Move forward through records.

Use streaming when rows can be handled once, in order, and released after validation, transformation, export, or persistence.

streaming()rows()chunks()
RequirementModeWhy
Rich workbook accessNormalRandom cell access, styles, images, formulas, and workbook metadata.
Small configuration workbookNormalConvenience matters more than incremental row processing.
One-pass database importStreamingProcess records in order without retaining the complete result.
Preview a small record sampleEitherUse a row limit; choose streaming if the source itself can still be very large.
Very large row-oriented workloadStreamingPrefer the native forward-only path and incremental terminal methods.
Memory model

The important difference is what stays alive while the read continues.

Streaming reduces retained row data only when the underlying reader can advance without materializing the full source structure.

Normal
  1. 01
    Open the workbook

    Build the structures needed for convenient workbook access.

  2. 02
    Inspect freely

    Revisit cells, styles, images, and metadata as the workflow requires.

  3. 03
    Retain more state

    Memory use can grow with workbook content and the structures your workflow needs.

Streaming
  1. 01
    Open a forward reader

    Prepare the selected worksheet for sequential processing.

  2. 02
    Yield rows or chunks

    Hand records to the application as they become available.

  3. 03
    Release completed data

    Keep only the current work set when the native streaming path is available.

API shape

The code should reveal whether the workflow needs random access or one-pass processing.

Keep mode selection close to the operation. A reviewer should be able to understand the memory and access intent from the pipeline itself.

Normal mode
$sheet = MnbExcel::read('report.xlsx')
    ->sheet('Summary')
    ->normal();

$value = $sheet->cell('D12');
$style = $sheet->cellStyle('D12');
$images = $sheet->images();
Streaming mode
$sheet = MnbExcel::read('orders.xlsx')
    ->sheet('Orders')
    ->withHeaderRow(1)
    ->streaming();

foreach ($sheet->chunks(1000) as $rows) {
    // Validate, transform, and persist this batch.
}
Streaming boundary

A streaming session can still materialize data if the terminal method asks it to.

Choose the terminal method with the same care as the read mode. Also distinguish portable fallback support from a truly bounded-memory native path.

MethodBehaviorEffect
rows()IncrementalYield rows as the application consumes them.
chunks()IncrementalYield bounded batches for validation, transformation, or persistence.
eachRow() / chunk()IncrementalProcess through callbacks without collecting the full result.
toArray()MaterializesCollect the result in PHP memory; use intentionally for smaller outputs.