Core concepts
Errors, Results, and Safe Boundaries
Design predictable exception handling, row-level policies, result checks, and user-safe messages.
MnbExcelErrorHandler::registerDeveloperMode()MnbExcelException::toErrorArray()MnbExcel::safeError()MnbExcel::errorReport()ReadSession::rowErrors()Classify the failure before deciding how the application should react.
Not every problem belongs in the same catch block. Separate programming faults, operation-level exceptions, recoverable row issues, and returned result contracts.
Do not reclassify a programming mistake as invalid spreadsheet input.
Keep structured diagnostics on the server and return a public-safe message.
Continue valid rows only when the workflow explicitly allows partial recovery.
Check documented status, counts, paths, warnings, and errors before declaring completion.
Keep detailed diagnostics inside the system. Return safe information outside it.
Catch spreadsheet operation failures where your application can log them, translate them into the correct HTTP/CLI response, and avoid exposing vendor traces or sensitive paths.
- Public response
MnbExcel::safeError()produces a message suitable for the caller-facing boundary.- Server diagnostic
MnbExcel::errorReport(..., debug: true)ortoErrorArray(debug: true)preserves structured troubleshooting detail.- Programming errors
- Wrong return-type assumptions, undefined methods, and other PHP faults should be fixed as code defects, not converted into spreadsheet validation messages.
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 global renderer for manual debugging, not as the production error boundary.
The handler is opt-in and gives uncaught MNB exceptions a cleaner developer-facing representation. Production applications should still own their catch/log/respond behavior.
use Mnb\PHPExcel\Support\MnbExcelErrorHandler;
MnbExcelErrorHandler::registerDeveloperMode();Let row policy handle bad records only when partial progress is acceptable.
A malformed row is different from a workbook that cannot be opened. Use row-level collection for workflows that may continue, then inspect the collected errors before final success.
use Mnb\PHPExcel\Reader\Options\RowErrorPolicy;
$session = MnbExcel::read($path)
->withHeaderRow(1)
->onRowError(RowErrorPolicy::Collect);
foreach ($session->rows() as $row) {
// Valid rows continue through the pipeline.
}
$errors = $session->rowErrors();Do not silently continue just because a row-level API exists; the business workflow decides whether partial processing is valid.
When collection is enabled, valid rows can continue through the pipeline while bad-row diagnostics are retained.
rowErrors() before completion.A loop finishing successfully does not mean every source record was accepted.
A returned array is an operation result, not proof that the operation fully succeeded.
Import, queue, scheduler, validation, large-file, and structured worksheet operations can return native PHP arrays. Read the documented fields before deciding what your application reports next.
- Outcome
- Confirm the documented success/failure state before returning a successful application response.
- Processed and failed rows
- Compare counts so partial work is visible rather than silently treated as complete.
- Failed-row details
- Surface or persist row diagnostics when the operation exposes them.
- Output path or artifact
- Verify the expected file or destination exists before reporting completion.
- Warnings and errors
- Treat warnings as part of the operation contract, not console noise to ignore.