Skip to content
PHP 8.1+ Open source Developer documentation
Tools Packagist
Docs v2.0.6
Documentation versions v2.0.6Current v2.0.5Maintenance v2.0.4Maintenance v2.0.3Maintenance v2.0.0Initial v2 Compare versions →
MNB PHPExcelDeveloper Guide
AI

Reference

Version 2 Upgrade Guide

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

Level
Maintainer
Reading time
13 min
Package
mnb/mnb-phpexcel
Updated
Upgrade map

Move to v2 without carrying old package assumptions forward.

The supported path is a coordinated 2.x release line: align dependencies first, remove v1-era compatibility assumptions, then verify the complete distribution before tagging.

  1. 01Align dependenciesMain package + ^2.0 release family
  2. 02Remove old assumptionsNative XLS + clearer package boundaries
  3. 03Verify and releaseTests, immutable tag, Packagist, docs
Architecture changes

These are the boundaries that most often affect existing installations and release automation.

Common release family

All split repositories are tagged v2.0.0 and internal Composer requirements use ^2.0.

Legacy XLS

The main package uses a native BIFF8/OLE reader and writer with no PhpSpreadsheet dependency or fallback.

Generic Database

The database package depends on Core and PDO; it does not install XLSX.

Large XLSX imports

The main package owns direct large-XLSX-to-PDO orchestration.

Core boundaries

Core uses capability interfaces and actionable optional-package errors instead of importing concrete format classes.

XLSX boundaries

Import-template generation and compatibility fixtures are package-local and do not require Application.

Dependency alignment

Install the main distribution and keep Composer on the 2.x line.

The public documentation targets mnb/mnb-phpexcel. Split repositories remain implementation and release units rather than extra installation steps for normal documentation users.

Install

Require the supported major line.

Terminal
composer require mnb/mnb-phpexcel:^2.0

Use the complete main package when following the public guides and examples.

composer.json

Make the release constraint explicit.

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

After a patch release is published, run composer update mnb/mnb-phpexcel -W to refresh the lock file and installed code.

Migration cleanup

Remove compatibility assumptions that no longer describe v2.

Do this before diagnosing runtime differences. Old class names, fallback expectations, and package assumptions can hide the real upgrade state.

01

Replace Compatibility\XlsReader and Compatibility\XlsWriter with Reader\XlsReader, Writer\XlsWriter, or Format\Xls.

02

Remove phpoffice/phpspreadsheet when no unrelated dependency still requires it.

03

Use MnbExcel for normal reads and writes; specialized Format\Xlsx APIs are included in the same main package.

04

Treat LargeExcelDatabaseImportEngine as part of the main package.

05

Treat ODS as a reader-only module.

Maintenance line

Apply the compatible v2.0.1 through v2.0.6 maintenance changes.

Projects using ^2.0 can accept these compatible patch releases. Existing tags remain immutable; fixes belong in new patch tags.

v2.0.1
XMLReader initialization

Native XMLReader initialization no longer reads libxml-backed properties before the first node.

v2.0.2
Sheet selection errors

Worksheet selection throws actionable SheetSelectionException errors with stable codes and caller context.

v2.0.3
Sheet and empty-state helpers

Added active-sheet discovery, optional sheet selection, normalized empty checks, and assertHasRows().

v2.0.4
Developer error rendering

Added the opt-in MnbExcelErrorHandler for clean developer text, HTML, or JSON rendering.

v2.0.5
Structured row counts

Structured sheet/workbook summaries distinguish total, source, explicit/implicit empty, skipped, header, and returned row counts.

v2.0.6
Current documentation target

Current mono-library release and documentation version alignment.

Release order

Publish the main package in a repeatable sequence.

Composer versions come from Git tags. Do not add a manual version field to the library Composer file.

  1. 01

    Merge tested changes into main.

  2. 02

    Run Composer validation and the full test suite.

  3. 03

    Create an immutable patch tag such as v2.0.6.

  4. 04

    Push main and the tag.

  5. 05

    Refresh Packagist and verify the installed dist archive.

  6. 06

    Deploy the matching documentation site.

Release gate

Verify the distribution before you publish the tag.

The upgrade is not complete when Composer resolves. Validate package metadata, runtime behavior, generated files, database paths, and the matching documentation deployment.

  • 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.