feat(polyfill): detached Worksheet + addSheet, eager alias surface, value binder, IOFactory registration

[saifulferoz]

What

Four PhpSpreadsheet-parity gaps hit by the ERP report suite, already validated against it (19/19 report generator tests under EASY_EXCEL_ALIAS=strict):

1. Detached new Worksheet() + Spreadsheet::addSheet($sheet, ?$index) — the multi-sheet idiom used by composite/filter-loop reports (new Worksheet(); setTitle(); $spreadsheet->addSheet($ws, $i)) fataled with "Too few arguments to Worksheet::__construct()". Both ctor args are now optional; title get/set works while detached; every native-touching call routes through workbookHandle() which throws a clear "attach it first" message; rebindParent() rejects cross-workbook moves; addSheet rejects duplicate titles (matching PhpSpreadsheet).

2. Eager alias surface (aliasCompatSurface()) — PHP never autoloads for instanceof/typed-parameter checks, so a lazily-aliased class that was only ever returned (e.g. Worksheet from getActiveSheet()) failed consumer type hints like function (Worksheet $ws). Every implemented Compat class is aliased at bootstrap; lazy aliasing stays for unimplemented classes (strict throw / fallback defer).

3. Workbook-level value binder — Spreadsheet::setValueBinder()/getValueBinder() (PhpSpreadsheet ≥ 2.x); wins over the legacy static Cell::setValueBinder(); setCellValue()/fromArray() route through it.

4. IOFactory::registerWriter()/registerReader() + createReaderForFile() — apps that plug custom writers (e.g. an Html-based Pdf writer) run unchanged; registered entries are consulted before the built-ins; new Reader\IReader contract + Writer\Exception/Reader\Exception (also open upstream as feat(polyfill): IOFactory registerWriter/registerReader + createReade… xiidea/easy-excel#2).

Testing

• php tests/run.php green on the branch.
• ERP suite: 19/19 under strict alias mode (previously 6 binder errors + 1 ctor error + latent type-check failures).
• Verified today in the ERP dev stack (vendor-patched from this branch): detached construct + setTitle + addSheet + duplicate-title guard + typed-param/instanceof checks all pass under the Compat engine, and the composite multi-sheet report saves with the correct sheet list.

🤖 Generated with Claude Code