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

Reading workbooks

Read an XLSX Workbook

Open an XLSX workbook, inspect its worksheets, choose the right row shape, and process records with a deliberate terminal method.

Level
Beginner
Reading time
9 min
Package
mnb/mnb-phpexcel
Updated
MnbExcel::read()ReadSession::sheetNames()ReadSession::activeSheetInfo()ReadSession::inspect()ReadSession::sheet()ReadSession::withHeaderRow()ReadSession::withoutHeaderRow()ReadSession::rows()ReadSession::toArray()
Workbook first

Open once, inspect the workbook, then choose the worksheet deliberately.

XLSX files can contain several worksheets and an active-sheet setting. Inspect that structure before business code assumes where the data lives.

  1. 01OpenCreate one read session.
  2. 02InspectSee sheets and workbook metadata.
  3. 03SelectChoose the intended worksheet.
  4. 04ShapeDecide header or positional rows.
  5. 05ExecuteStream or collect the result.
sheetNames()
Discover worksheet names before selecting one by business meaning.
activeSheetInfo()
Inspect the workbook-defined active worksheet instead of assuming the first tab is primary.
inspect()
Use workbook-level inspection when the application needs structure before row processing starts.
Inspect workbook
$workbook = MnbExcel::read('orders.xlsx');

$sheetNames = $workbook->sheetNames();
$activeSheet = $workbook->activeSheetInfo();
$inspection = $workbook->inspect();
Choose the row shape

Use named rows for records. Use positional rows for matrices.

Header handling changes the PHP shape your loop receives. Choose it from the document model rather than from habit.

Business records

Associative rows survive column reordering more safely.

Use a declared header row when columns have stable business names such as Order ID, Email, Amount, or Status.

sheet()withHeaderRow()rows()
Named business records
$orders = MnbExcel::read('orders.xlsx')
    ->sheet('Orders')
    ->withHeaderRow(1);

foreach ($orders->rows() as $row) {
    printf("%s — %0.2f\n", $row['Order ID'], $row['Amount']);
}
Grid / matrix data

Positional rows preserve coordinate-oriented structure.

Use numeric indexes when column position is itself meaningful and there is no business header contract.

sheet()withoutHeaderRow()rows()
Positional matrix rows
$rows = MnbExcel::read('matrix.xlsx')
    ->sheet(1)
    ->withoutHeaderRow()
    ->rows();

foreach ($rows as $row) {
    $firstCell = $row[0] ?? null;
}
Choose the terminal result

Stream records when you can process them incrementally. Collect only when the dataset belongs in memory.

Both approaches are valid. The important boundary is the type returned by the terminal method and how much row data the application retains.

MethodReturnsRetentionUse when
rows()Generator / iterable rowsIncremental

Each record can be validated, transformed, persisted, or exported as it arrives.

toArray()Native PHP arrayCollected

The complete result is modest enough that later application logic genuinely benefits from an in-memory array.

Incremental

Keep the read and the processing loop together.

This makes the application’s one-pass intent visible.

Stream rows
$session = MnbExcel::read('orders.xlsx')
    ->sheet('Orders')
    ->withHeaderRow(1);

foreach ($session->rows() as $row) {
    processOrder($row);
}
Collected

After toArray(), work with a normal PHP array.

Session methods are no longer available on the returned array.

Collect rows
$rows = MnbExcel::read('small-reference.xlsx')
    ->sheet('Countries')
    ->withHeaderRow(1)
    ->toArray();

if ($rows === []) {
    return;
}

foreach ($rows as $row) {
    processCountry($row);
}
Keep the guide focused

Move to the specialist guide when sheet rules, terminal choice, or file size becomes the main problem.

This page covers the normal XLSX reading path. The linked guides go deeper without making the basic workflow harder to scan.