Deprecate `ByColumnAndRow()` methods in Worksheet

[MarkBaker]

Discussed in #2706

^{Originally posted by MarkBaker March 20, 2022}
I'm planning version 2.0 with some bc breaks, and I'm looking at dropping methods like setCellValueByColumnAndRow() which accepts column and row number arguments, leaving only setCellValue() which requires a cell address as a string value(e.g. 'C5').
There are 14 such methods defined in the WorkSheet class:

• setCellValueByColumnAndRow() has equivalent setCellValue()
• setCellValueExplicitByColumnAndRow() has equivalent setCellValueExplicit()
• getCellByColumnAndRow() has equivalent getCell()
• cellExistsByColumnAndRow() has equivalent cellExists()
• getStyleByColumnAndRow() has equivalent getStyle()
• setBreakByColumnAndRow() has equivalent setBreak()
• mergeCellsByColumnAndRow() has equivalent mergeCells()
• unmergeCellsByColumnAndRow() has equivalent unmergeCells()
• protectCellsByColumnAndRow() has equivalent protectCells()
• unprotectCellsByColumnAndRow() has equivalent unprotectCells()
• setAutoFilterByColumnAndRow() has equivalent setAutoFilter()
• freezePaneByColumnAndRow() has equivalent freezePane()
• getCommentByColumnAndRow() has equivalent getComment()
• setSelectedCellByColumnAndRow() has equivalent setSelectedCells()

There is some inconsistency here, with other methods that only accept a cell address like IV255 and that have no "byColumnAndRow" eqivalent (e.g setTopLeftCell() and setSelectedCell()); so this deprecation will provide more consistency.

The base methods already provide more flexibility than the byColumnAndRow() methods

There are also a couple of column-only methods:

• getColumnDimensionByColumn() has equivalent getColumnDimension()
• insertNewColumnBeforeByIndex() has equivalent insertNewColumnBefore()

---

A CellAddress object could be defined with static creator methods like fromRowAndColumn($rowIndex, $columnIndex), fromColumnAndRow($columnIndex, $rowIndex), fromCoordinate($cellAddress), etc; and provide getters to retrieve rowIndex, columnIndex, columnString, cellAddress, etc, giving it a lot more flexibility.

These base methods will be re-defined to accept either a string, an array of columnId/RowId or a CellAddress object.

setCellValue(string|array|CellAddress $coordinate, $value){}

Those that accept a range of cells will be re-defined to accept either a string, an array of columnId/RowId, a CellAddress object, or a CellRange object.

mergeCells(string|array|CellAddress|CellRange $range){}

[russeljo]

This is not a good solution to simply remove the method. It would have been better to keep it as an alias with a deprecated note. After the update, it just stopped working. And in the IDE, the method is now treated as if it doesn’t exist. This is very inconvenient. You have to investigate what exactly changed, dig into the changelog, search outside the installed library itself, and only then discover that this method no longer exists.

[oleibman]

@russeljo The methods were marked as deprecated by PR #3183 in November 2022 (actually earlier, but the earlier change misspelled "deprecated"). The correct annotation was used starting with release 1.26. The deprecated methods were removed with release 2 in December 2023, over a year later. There were definitely aspects that could have been improved in the process, but I think your particular complaint was indeed handled as you suggested it ought to have been.

[dakujem]

I assume there are more of us who are only upgrading from v1 because of PHP 8.4. 😁

But the chore is not that heavy:

1. search for all the ByColumnAndRow( occurences
2. replace with the array parameter variant like this $sheet->getStyle([$col, $row]), except for mergeCells
3. for mergeCellsByColumnAndRow use CellRange and CellAddress::fromColumnAndRow calls, like this:

   $sheet->mergeCells(new CellRange(
       CellAddress::fromColumnAndRow($col, $row), 
       CellAddress::fromColumnAndRow($col + $offset, $row),
   ))
   

You don't really need to study each and every change.