MNB PHPExcelDeveloper Guide
v2.0.5
Core concepts

Errors, Results, and Safe Boundaries

Design predictable exception handling, row-level policies, result checks, and user-safe messages.

Updated

LevelIntermediateReading time9 minPackagemnb/mnb-phpexcel
MnbExcelErrorHandler::registerDeveloperMode()MnbExcelException::toErrorArray()MnbExcel::safeError()MnbExcel::errorReport()ReadSession::rowErrors()

What you will learn

  • Separate programming errors from invalid input rows.
  • Return safe public messages without losing server diagnostics.
  • Inspect structured operation results before declaring success.

Catch exceptions at an application boundary#

PHP
try {
    $result = MnbExcel::importProducts($path, $pdo, 'products', $options);
} catch (Throwable $error) {
    $public = MnbExcel::safeError($error);
    error_log(json_encode(MnbExcel::errorReport($error, debug: true)));

    http_response_code(422);
    header('Content-Type: application/json');
    echo json_encode($public);
}

Use the opt-in developer renderer during manual testing#

PHP
use Mnb\PHPExcel\Support\MnbExcelErrorHandler;

MnbExcelErrorHandler::registerDeveloperMode();

// Uncaught MNB exceptions now render a clean code and actionable message
// instead of PHP's default fatal-error heading and vendor stack trace.

Use row policies for recoverable bad records#

PHP
use Mnb\PHPExcel\Reader\Options\RowErrorPolicy;

$session = MnbExcel::read($path)
    ->withHeaderRow(1)
    ->onRowError(RowErrorPolicy::Collect);

foreach ($session->rows() as $row) {
    // Valid rows continue.
}

$errors = $session->rowErrors();

Treat result arrays as contracts#

Import, queue, scheduler, validation, large-file operations, and structured worksheet conversions return native PHP arrays. Check documented status, row counts, failed rows, output paths, warnings, and errors. After a terminal method such as toArray() or toStructuredSheetArray(), use array operations rather than ReadSession methods.