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

ReaderOptions and Read Pipelines

Compose immutable read behavior for ranges, columns, headers, formulas, passwords, progress, and errors.

Level
Intermediate
Reading time
10 min
Package
mnb/mnb-phpexcel
Updated
ReaderOptions::defaults()withRange()withColumns()withMode()withPassword()withRowErrorPolicy()
Configuration ownership

Put shared policy in ReaderOptions. Keep one-off choices on the session.

The APIs overlap intentionally. The useful distinction is where the configuration belongs, not which syntax is shorter.

Shared baseline

Reusable reader policy

Use ReaderOptions when multiple readers, services, or jobs should start from the same immutable configuration.

ReaderOptions::defaults()withRange()withMode()
Local operation

Read-specific overrides

Use fluent session methods when sheet selection, ranges, projection, progress, or error handling belongs to one read operation.

sheet()range()projectColumns()streaming()
Immutable baseline

Build once, then derive another configuration without shared-state surprises.

Each with…() call returns the configured value you continue chaining. Keep the baseline reusable and create a different option set when another workflow needs different behavior.

01Start from defaults

Create an explicit baseline instead of scattering reader flags across application code.

02Compose the policy

Range, projection, mode, formulas, row errors, and progress stay together.

03Reuse or derive

Pass the same options object to another read, or build a modified configuration for another workflow.

ReaderOptions.php
use Mnb\PHPExcel\Reader\Options\ReadMode;
use Mnb\PHPExcel\Reader\Options\ReaderOptions;
use Mnb\PHPExcel\Reader\Options\RowErrorPolicy;

$options = ReaderOptions::defaults()
    ->withRange(startRow: 2, endRow: 100000, startColumn: 'A', endColumn: 'H')
    ->withColumns(['Order ID', 'Customer', 'Amount'])
    ->withMode(ReadMode::Streaming)
    ->withFormulaMode('cached')
    ->withRowErrorPolicy(RowErrorPolicy::Collect)
    ->withProgress($progressCallback, everyRows: 1000);
Option groups

Know which part of the read each option controls.

Keep scope, execution, interpretation, and operational behavior explicit. That makes a read easier to review and reproduce.

ConcernMethodControls
Physical rangewithRange()Limit the source rows and columns considered by the read.
Source projectionwithColumns()Select the source fields the application actually needs.
Execution modewithMode()Choose the configured read mode, including streaming where appropriate.
Header discoverywithAutoHeader()Control automatic header detection when a fixed header row is not supplied locally.
Encrypted inputwithPassword()Provide the password required by a protected input file.
Formula representationwithFormulaMode()Choose how formula cells are represented to the read pipeline.
Bad-row behaviorwithRowErrorPolicy()Decide how row-level failures are handled by the read.
Progress reportingwithProgress()Attach progress reporting and choose the row interval for callbacks.
Apply the configuration

Pass the baseline at the entry point, then keep local context close to the read.

This keeps reusable policy separate from sheet-specific details while still producing one understandable pipeline.

Shared policy
$options travels with the read entry point.
Workbook context
sheet() and withHeaderRow() stay beside the workbook operation that needs them.
Rule of thumb
Use ReaderOptions across boundaries; use session methods for local intent.
Apply the baseline
$session = MnbExcel::read('orders.xlsx', $options)
    ->sheet('Orders')
    ->withHeaderRow(1);