Read Excel Files Safely

Install the correct package#

composer require mnb/mnb-phpexcel:^2.0

composer require mnb/mnb-phpexcel-xlsx:^2.0

The full package exposes MnbExcel. The individual package exposes Xlsx. Both create the same read-session API after the workbook is opened.

Open, inspect, select, and stream#

use Mnb\PHPExcel\MnbExcel;

$path = __DIR__ . '/storage/imports/orders.xlsx';
$workbook = MnbExcel::read($path);

use Mnb\PHPExcel\Format\Xlsx;

$path = __DIR__ . '/storage/imports/orders.xlsx';
$workbook = Xlsx::read($path);

$inspection = $workbook->inspect();
$sheetNames = $workbook->sheetNames();

if ($sheetNames === []) {
    throw new RuntimeException('The workbook has no readable worksheets.');
}

$sheet = $workbook->sheetIfExists('Orders')
    ?? $workbook->activeSheet();

$session = $sheet
    ->withHeaderRow(1)
    ->withOptions([
        'skip_empty_rows' => true,
        'max_rows' => 5000,
    ])
    ->assertHasRows();

foreach ($session->rows() as $row) {
    echo $row['Order ID'] . ' — ' . $row['Customer'] . PHP_EOL;
}

Developer contract#

Returns from read()

ReadSession

Returns from rows()

Generator<int, array<string, mixed>>

Reads immediately

read() creates a session; rows() begins row consumption.

Memory behavior

Rows are yielded one at a time when the native streaming path is available.

Empty check

hasRows(), isEmpty(), or assertHasRows() on the session.

Errors

MnbExcelException for library failures; application validation may throw RuntimeException.

ORD-1001 — Arjun Stores
ORD-1002 — Northwind Retail

Choose how to consume the data#

Open the complete reading-method decision table →

Common mistake: treating an array like a session#

$rows = $session->toArray();
$rows->isEmpty();

$rows = $session->toArray();

if ($rows === []) {
    echo 'No rows found.';
}

if ($session->isEmpty()) {
    echo 'No rows found.';
}

Review all common mistakes →

Continue the workflow#