MNB PHPExcelDeveloper Guide
v2.0.5
Reading workbooks

Sheet Selection, Empty Rows, and Counts

Discover active worksheets, select optional sheets safely, distinguish read sessions from terminal arrays, and report total, empty, skipped, and returned row counts.

Updated

LevelIntermediateReading time13 minPackagemnb/mnb-phpexcel
sheetNames()hasSheet()sheetIfExists()sheetOrActive()activeSheetInfo()hasRows()isEmpty()assertHasRows()toArray()toStructuredSheetArray()

What you will learn

  • Choose strict selection, optional selection, or active-sheet fallback intentionally.
  • Check normalized data rows before collecting terminal arrays.
  • Interpret physical, sparse, empty, skipped, header, and final returned row counts.

Inspect available and active worksheets#

PHP
use Mnb\PHPExcel\Format\Xlsx;

$workbook = MnbExcel::read('report.xlsx');

print_r($workbook->sheetNames());
print_r($workbook->activeSheetInfo());

echo $workbook->activeSheetName();
echo $workbook->activeSheetIndex(); // 1-based

XLSX reads Excel workbook activeTab metadata. When active-sheet metadata is absent, the first readable worksheet is used.

Choose strict or optional selection#

MethodBehavior
sheet('Data')Strict. Throws a SheetSelectionException when the name or 1-based index is invalid.
hasSheet($value)Returns a Boolean and never selects a sheet. Empty or null values return false.
sheetIfExists($value)Returns a selected ReadSession or null.
sheetOrActive($value)Uses the active sheet for null or an empty string; a non-empty typo remains an error.
activeSheet()Selects the workbook active sheet explicitly.
PHP
$sheetName = trim((string) ($_GET['sheet'] ?? ''));

$sheet = MnbExcel::read('report.xlsx')
    ->sheetOrActive($sheetName)
    ->withHeaderRow(1);

Render MNB exceptions without raw vendor traces#

import.php
use Mnb\PHPExcel\Format\Xlsx;
use Mnb\PHPExcel\Support\MnbExcelException;

try {
    $rows = MnbExcel::read('report.xlsx')
        ->sheet('Data')
        ->withHeaderRow(1)
        ->rows();

    foreach ($rows as $row) {
        // Process data.
    }
} catch (MnbExcelException $error) {
    print_r($error->toErrorArray(debug: true));
}

An uncaught exception is rendered by PHP and includes a stack trace. Catch MnbExcelException in application code or register the opt-in MNB handler during development. Stable sheet error codes include MNB_SHEET_SELECTION_REQUIRED, MNB_SHEET_INDEX_INVALID, MNB_SHEET_NAME_INVALID, MNB_SHEET_NOT_FOUND, and MNB_SHEET_NAME_AMBIGUOUS.

Check normalized rows before conversion#

PHP
$session = MnbExcel::read('report.xlsx')
    ->sheetOrActive($sheetName)
    ->withHeaderRow(1)
    ->withOptions([
        'skip_empty_rows' => true,
    ]);

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

$session->assertHasRows();

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

hasRows() and isEmpty() evaluate normalized data after the current header, range, projection, offset, limit, filters, and empty-row options. A header-only worksheet is therefore empty when a header row is enabled.

Understand terminal array methods#

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

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

foreach ($rows as $row) {
    print_r($row);
}

$structured = $session->toStructuredSheetArray([
    'header_row' => 1,
    'skip_empty_rows' => true,
    'include_cell_metadata' => false,
    'row_format' => 'flat',
]);

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

Report total, empty, skipped, and returned rows#

PHP
$data = $session->toStructuredSheetArray([
    'header_row' => 1,
    'skip_empty_rows' => true,
    'include_cell_metadata' => false,
]);

$counts = $data['summary']['row_counts'];

printf("Logical row positions: %d\n", $counts['total']);
printf("Stored row records: %d\n", $counts['source_records']);
printf("Empty rows: %d\n", $counts['empty']);
printf("Explicit empty rows: %d\n", $counts['explicit_empty']);
printf("Implicit sparse gaps: %d\n", $counts['implicit_empty']);
printf("Skipped empty records: %d\n", $counts['skipped_empty']);
printf("Header rows consumed: %d\n", $counts['header']);
printf("Final returned rows: %d\n", $counts['returned']);
CountMeaning
totalLogical row positions from the first selected physical row through the last, including sparse gaps.
source_recordsRow records physically supplied by the format reader.
emptyExplicit empty records plus implicit missing row-number positions.
explicit_emptyStored rows whose cells contain no values.
implicit_emptyMissing row numbers in sparse formats such as XLSX.
skipped_emptyExplicit empty source records removed because skip_empty_rows is enabled.
headerConsumed header rows, normally zero or one.
returnedFinal data records after header and empty-row processing.

Convenience aliases are available as summary.total_rows, summary.empty_rows, and summary.returned_rows. Existing fields such as source_rows, processed_rows, data_rows, and skipped_empty_rows remain supported.