From 02a6513ec8a62372f158f43863c0a4cd227c4a88 Mon Sep 17 00:00:00 2001 From: oleibman <10341515+oleibman@users.noreply.github.com> Date: Sat, 9 Dec 2023 07:46:50 -0800 Subject: [PATCH] Remove byColumnAndRow Examples From Documentation (#3816) * Remove byColumnAndRow Examples From Documentation Responding to https://github.com/PHPOffice/PhpSpreadsheet/discussions/2706#discussioncomment-7798739. * Migration From PHPExcel - Charts Updated section to recommend use of mitoteam/jpgraph. * Update accessing-cells.md Remove 'by coordinate' from headings. --- docs/topics/accessing-cells.md | 48 ++++++-------------------- docs/topics/migration-from-PHPExcel.md | 40 +++++++++++---------- 2 files changed, 32 insertions(+), 56 deletions(-) diff --git a/docs/topics/accessing-cells.md b/docs/topics/accessing-cells.md index d1818c3d03..149172a57e 100644 --- a/docs/topics/accessing-cells.md +++ b/docs/topics/accessing-cells.md @@ -2,10 +2,13 @@ Accessing cells in a Spreadsheet should be pretty straightforward. This topic lists some of the options to access a cell. +For all of these, the cell can be accessed by coordinate (e.g. `B3`), +by an array of column index (where A is 1) and row (e.g. `[2, 3]`), +or as a CellAddress object (e.g. `new CellAddress('B3', /* optional */ $worksheet)`. -## Setting a cell value by coordinate +## Setting a cell value -Setting a cell value by coordinate can be done using the worksheet's +Setting a cell value can be done using the worksheet's `setCellValue()` method. ```php @@ -13,10 +16,10 @@ Setting a cell value by coordinate can be done using the worksheet's $spreadsheet->getActiveSheet()->setCellValue('A1', 'PhpSpreadsheet'); // Set cell A2 with a numeric value -$spreadsheet->getActiveSheet()->setCellValue('A2', 12345.6789); +$spreadsheet->getActiveSheet()->setCellValue([1, 2], 12345.6789); // Set cell A3 with a boolean value -$spreadsheet->getActiveSheet()->setCellValue('A3', TRUE); +$spreadsheet->getActiveSheet()->setCellValue(new CellAddress('A3'), TRUE); // Set cell A4 with a formula $spreadsheet->getActiveSheet()->setCellValue( @@ -318,7 +321,7 @@ $spreadsheet->getActiveSheet() ![07-simple-example-4.png](./images/07-simple-example-4.png) -## Retrieving a cell value by coordinate +## Retrieving a cell value To retrieve the value of a cell, the cell should first be retrieved from the worksheet using the `getCell()` method. A cell's value can be read @@ -350,37 +353,6 @@ the cell's `getFormattedValue()` method. $cellValue = $spreadsheet->getActiveSheet()->getCell('A6')->getFormattedValue(); ``` -## Setting a cell value by column and row - -Setting a cell value by coordinate can be done using the worksheet's -`setCellValueByColumnAndRow()` method. - -```php -// Set cell A5 with a string value -$spreadsheet->getActiveSheet()->setCellValueByColumnAndRow(1, 5, 'PhpSpreadsheet'); -``` - -**Note:** that column references start with `1` for column `A`. - -## Retrieving a cell value by column and row - -To retrieve the value of a cell, the cell should first be retrieved from -the worksheet using the `getCellByColumnAndRow()` method. A cell’s value can -be read again using the following line of code: - -```php -// Get the value from cell B5 -$cellValue = $spreadsheet->getActiveSheet()->getCellByColumnAndRow(2, 5)->getValue(); -``` - -If you need the calculated value of a cell, use the following code. This -is further explained in [the calculation engine](./calculation-engine.md). - -```php -// Get the value from cell A4 -$cellValue = $spreadsheet->getActiveSheet()->getCellByColumnAndRow(1, 4)->getCalculatedValue(); -``` - ## Retrieving a range of cell values to an array It is also possible to retrieve a range of cell values to an array in a @@ -487,7 +459,7 @@ echo '' . "\n"; for ($row = 1; $row <= $highestRow; ++$row) { echo '' . PHP_EOL; for ($col = 1; $col <= $highestColumnIndex; ++$col) { - $value = $worksheet->getCellByColumnAndRow($col, $row)->getValue(); + $value = $worksheet->getCell([$col, $row])->getValue(); echo '' . PHP_EOL; } echo '' . PHP_EOL; @@ -508,7 +480,7 @@ $worksheet = $spreadsheet->getActiveSheet(); $highestRow = $worksheet->getHighestDataRow(); // e.g. 10 $highestColumn = $worksheet->getHighestDataColumn(); // e.g 'F' // Increment the highest column letter -$highestColumn++; +++$highestColumn; echo '
' . $value . '
' . "\n"; for ($row = 1; $row <= $highestRow; ++$row) { diff --git a/docs/topics/migration-from-PHPExcel.md b/docs/topics/migration-from-PHPExcel.md index 4258a9dd07..e3ba71752d 100644 --- a/docs/topics/migration-from-PHPExcel.md +++ b/docs/topics/migration-from-PHPExcel.md @@ -222,14 +222,18 @@ $writer = new \PhpOffice\PhpSpreadsheet\Writer\Pdf\Mpdf($spreadsheet); ### Rendering charts -When rendering charts for HTML or PDF outputs, the process was also simplified. And while -JpGraph support is still available, it is unfortunately not up to date for latest PHP versions -and it will generate various warnings. - -If you rely on this feature, please consider -contributing either patches to JpGraph or another `IRenderer` implementation (a good +When rendering charts for HTML or PDF outputs, the process was simplified. +And, while JpGraph support is still available, +the version distributed via Composer is no longer maintained, +so you would need to install the current version manually. +If you rely on this package, please consider +contributing patches either to JpGraph or another `IRenderer` implementation (a good candidate might be [CpChart](https://github.com/szymach/c-pchart)). +The package [mitoteam/jpgraph](https://github.com/mitoteam/jpgraph) +is distributed via Composer, and is fully compatible with Jpgraph. +We recommend that it be used for rendering. + Before: ```php @@ -245,13 +249,13 @@ After: Require the dependency via composer: ```sh -composer require jpgraph/jpgraph +composer require mitoteam/jpgraph ``` And then: ```php -Settings::setChartRenderer(\PhpOffice\PhpSpreadsheet\Chart\Renderer\JpGraph::class); +Settings::setChartRenderer(\PhpOffice\PhpSpreadsheet\Chart\Renderer\MtJpGraphRenderer::class); ``` ### PclZip and ZipArchive @@ -294,13 +298,13 @@ Refer to [the new documentation](./memory_saving.md) to see how to migrate. ### Dropped conditionally returned cell -For all the following methods, it is no more possible to change the type of -returned value. It always return the Worksheet and never the Cell or Rule: +For all the following methods, it is not possible to change the type of +returned value. They will always return the Worksheet and never the Cell or Rule: - Worksheet::setCellValue() -- Worksheet::setCellValueByColumnAndRow() +- Worksheet::setCellValueByColumnAndRow() (*deprecated*) - Worksheet::setCellValueExplicit() -- Worksheet::setCellValueExplicitByColumnAndRow() +- Worksheet::setCellValueExplicitByColumnAndRow() (*deprecated*) - Worksheet::addRule() Migration would be similar to: @@ -412,19 +416,19 @@ So the code must be adapted with something like: // Before $cell = $worksheet->getCellByColumnAndRow($column, $row); -for ($column = 0; $column < $max; $column++) { - $worksheet->setCellValueByColumnAndRow($column, $row, 'value ' . $column); +for ($column = 0; $column < $max; ++$column) { + $worksheet->setCellValueByColumnAndRow($column, $row, 'value'); } // After -$cell = $worksheet->getCellByColumnAndRow($column + 1, $row); +$cell = $worksheet->getCell([$column + 1, $row]); -for ($column = 1; $column <= $max; $column++) { - $worksheet->setCellValueByColumnAndRow($column, $row, 'value ' . $column); +for ($column = 1; $column <= $max; ++$column) { + $worksheet->setCellValue([$column, $row], 'value'); } ``` -All the following methods are affected: +All the following methods are affected, and all are now deprecated (see example above for how to replace them): - `PHPExcel_Worksheet::cellExistsByColumnAndRow()` - `PHPExcel_Worksheet::freezePaneByColumnAndRow()`