MNB PHPExcelDeveloper Guide
v2.0.5
Reference

Version 2 Upgrade Guide

Upgrade the main package to v2 with native XLS, improved package boundaries, and developer-facing maintenance APIs through v2.0.5.

Updated

LevelMaintainerReading time13 minPackagemnb/mnb-phpexcel

What you will learn

  • Understand the breaking API and implementation changes in v2.
  • Keep the main package on the supported 2.x release line.
  • Validate the complete main distribution before publishing tags.

Understand the v2 architecture changes#

Changev2 behavior
Common release familyAll split repositories are tagged v2.0.0 and internal Composer requirements use ^2.0.
Legacy XLSmnb/mnb-phpexcel is a fully native BIFF8/OLE reader and writer with no PhpSpreadsheet dependency or fallback.
Generic Databasemnb/mnb-phpexcel depends only on Core and PDO; it does not install XLSX.
Large XLSX importsThe new mnb/mnb-phpexcel package owns direct large-XLSX-to-PDO orchestration.
Core boundariesCore uses capability interfaces and actionable optional-package errors instead of importing concrete format classes.
XLSX boundariesImport-template generation and compatibility fixtures are package-local and do not require Application.

Install the main distribution#

Terminal
composer require mnb/mnb-phpexcel:^2.0

Update the Composer requirement#

composer.json
{
    "require": {
        "mnb/mnb-phpexcel": "^2.0"
    }
}

Run composer update mnb/mnb-phpexcel -W to refresh the lock file and installed code after publishing a patch release.

Remove old compatibility assumptions#

  • Remove direct use of Compatibility\XlsReader and Compatibility\XlsWriter; use Reader\XlsReader, Writer\XlsWriter, or Format\Xls.
  • Remove phpoffice/phpspreadsheet when no unrelated dependency requires it.
  • Use MnbExcel for normal reads and writes. Specialized Format\Xlsx APIs are included in the same main package.
  • LargeExcelDatabaseImportEngine is included in the main package.
  • Treat ODS as a reader-only module.

Apply the v2.0.1 through v2.0.5 Core maintenance updates#

ReleaseDeveloper-facing change
v2.0.1Native XMLReader initialization no longer reads libxml-backed properties before the first node.
v2.0.2Worksheet selection throws actionable SheetSelectionException errors with stable codes and caller context.
v2.0.3Added active-sheet discovery, optional sheet selection, normalized empty checks, and assertHasRows().
v2.0.4Added the opt-in MnbExcelErrorHandler for clean developer text, HTML, or JSON rendering.
v2.0.5Structured sheet/workbook summaries distinguish total, source, explicit/implicit empty, skipped, header, and returned row counts.

Projects using ^2.0 accept these compatible Core patch releases. Existing published tags are immutable; publish fixes under new patch tags rather than moving v2.0.0.

Publish the main package release#

Release order
1. Merge tested changes into main.
2. Run Composer validation and the full test suite.
3. Create an immutable patch tag such as v2.0.5.
4. Push main and the tag.
5. Refresh Packagist and verify the installed dist archive.
6. Deploy the matching documentation site.

Use Git tags as Composer versions; do not add a manual version field to the library Composer file.

Verify before release#

  • Run composer validate --strict in the main repository.
  • Run the main package syntax, smoke, integration, and release checks.
  • Run full facade and format interconnectivity tests.
  • Confirm composer why phpoffice/phpspreadsheet reports no MNB dependency.
  • Open representative native XLS and XLSX output in Microsoft Excel desktop and LibreOffice.
  • Test against every supported PDO driver with real transactions and duplicate constraints.
  • Validate the documentation site, clean links, code snippets, sitemap, and production routing.