[IMPROVEMENT] Excel: keep phpoffice/phpspreadsheet inside the Excel component

components/ILIAS/DataCollection/classes/Content/class.ilDclContentImporter.php

@@ -71,7 +71,6 @@ public function __construct(int $ref_id, ?int $table_id = null)
 
     /**
      * @throws ilException
-     * @throws \PhpOffice\PhpSpreadsheet\Exception
      * @throws ilDateTimeException
      */
     public function import(string $file, bool $simulate = false): array

components/ILIAS/DataCollection/classes/Fields/Text/class.ilDclTextRecordFieldModel.php

@@ -18,7 +18,7 @@
 
 declare(strict_types=1);
 
-use PhpOffice\PhpSpreadsheet\Cell\DataType;
+use ILIAS\Excel\CellType;
 
 class ilDclTextRecordFieldModel extends ilDclBaseRecordFieldModel
 {
@@ -50,7 +50,7 @@ public function fillExcelExport(ilExcel $worksheet, int &$row, int &$col): void
                 $col += 2;
             }
         } else {
-            $worksheet->setCell($row, $col, $value, DataType::TYPE_STRING);
+            $worksheet->setCell($row, $col, $value, CellType::STRING);
             $col++;
         }
     }

components/ILIAS/DataCollection/classes/Fields/TextSelection/class.ilDclTextSelectionRecordFieldModel.php

@@ -18,16 +18,13 @@
 
 declare(strict_types=1);
 
-use PhpOffice\PhpSpreadsheet\Cell\DataType;
+use ILIAS\Excel\CellType;
 
 class ilDclTextSelectionRecordFieldModel extends ilDclSelectionRecordFieldModel
 {
-    /**
-     * @throws \PhpOffice\PhpSpreadsheet\Exception
-     */
     public function fillExcelExport(ilExcel $worksheet, int &$row, int &$col): void
     {
-        $worksheet->setCell($row, $col, $this->getExportValue(), DataType::TYPE_STRING);
+        $worksheet->setCell($row, $col, $this->getExportValue(), CellType::STRING);
         $col++;
     }
 }

components/ILIAS/Excel/classes/class.ilExcel.php

@@ -26,6 +26,8 @@
 use PhpOffice\PhpSpreadsheet\Style\Border;
 use PhpOffice\PhpSpreadsheet\Cell\DataType;
 use ILIAS\FileUpload\MimeType;
+use ILIAS\Excel\CellType;
+use PhpOffice\PhpSpreadsheet\Exception as SpreadsheetException;
 
 /*
  * Wrapper for Microsoft Excel Import/Export (based on PHPSpreadsheet, formerPHPExcel which is deprecated)
@@ -62,17 +64,18 @@ class ilExcel
     protected Spreadsheet $workbook;
     protected string $type;
 
-    /**
-     * @throws \PhpOffice\PhpSpreadsheet\Exception
-     */
     public function __construct()
     {
         global $DIC;
 
         $this->lng = $DIC->language();
         $this->setFormat(self::FORMAT_XML);
         $this->workbook = new Spreadsheet();
-        $this->workbook->removeSheetByIndex(0);
+        try {
+            $this->workbook->removeSheetByIndex(0);
+        } catch (SpreadsheetException $e) {
+            throw new ilException($e->getMessage());
+        }
     }
 
     //
@@ -84,7 +87,11 @@ public function __construct()
      */
     public function loadFromFile(string $filename): void
     {
-        $this->workbook = IOFactory::load($filename);
+        try {
+            $this->workbook = IOFactory::load($filename);
+        } catch (SpreadsheetException $e) {
+            throw new ilException($e->getMessage());
+        }
     }
 
     //
@@ -116,8 +123,6 @@ public function setFormat(string $a_format): void
 
     /**
      * Add sheet
-     *
-     * @throws \PhpOffice\PhpSpreadsheet\Exception
      */
     public function addSheet(
         string $a_name,
@@ -133,8 +138,11 @@ public function addSheet(
         // see https://github.com/PHPOffice/PHPExcel/issues/79
         $a_name = ilStr::shortenTextExtended($a_name, 31);
 
-        $sheet = new Worksheet($this->workbook, $a_name);
-        $this->workbook->addSheet($sheet);
+        try {
+            $this->workbook->addSheet(new Worksheet($this->workbook, $a_name));
+        } catch (SpreadsheetException $e) {
+            throw new ilException($e->getMessage());
+        }
         $new_index = $this->workbook->getSheetCount() - 1;
 
         if ($a_activate) {
@@ -144,12 +152,13 @@ public function addSheet(
         return $new_index;
     }
 
-    /**
-     * @throws \PhpOffice\PhpSpreadsheet\Exception
-     */
     public function setActiveSheet(int $a_index): void
     {
-        $this->workbook->setActiveSheetIndex($a_index);
+        try {
+            $this->workbook->setActiveSheetIndex($a_index);
+        } catch (SpreadsheetException $e) {
+            throw new ilException($e->getMessage());
+        }
     }
 
 
@@ -283,15 +292,18 @@ public function setCellByCoordinates($a_coords, $a_value): void
      * @param int   $a_row
      * @param int   $col
      * @param mixed $value
-     * @param ?string  $datatype Explicit data type, see DataType::TYPE_*
+     * @param CellType|string|null $datatype Explicit data type; strings are deprecated, use {@see CellType}
      */
     public function setCell(
         int $a_row,
         int $col,
         $value,
-        ?string $datatype = null
+        CellType|string|null $datatype = null
     ): void {
         $coordinate = $this->getCoordByColumnAndRow($col, $a_row);
+        if ($datatype instanceof CellType) {
+            $datatype = $datatype->value;
+        }
 
         if ($datatype === DataType::TYPE_STRING) {
             $this->workbook->getActiveSheet()->setCellValueExplicit(
@@ -437,7 +449,6 @@ protected function prepareStorage(string $a_file_name): string
 
     /**
      * Send workbook to client
-     * @throws \PhpOffice\PhpSpreadsheet\Writer\Exception
      */
     public function sendToClient(string $a_file_name): void
     {
@@ -456,33 +467,37 @@ public function sendToClient(string $a_file_name): void
         }
         $tmp_name = ilFileUtils::ilTempnam();
 
-        $writer = IOFactory::createWriter($this->workbook, $this->format);
-        $writer->save($tmp_name);
+        try {
+            IOFactory::createWriter($this->workbook, $this->format)->save($tmp_name);
+        } catch (SpreadsheetException $e) {
+            throw new ilException($e->getMessage());
+        }
 
         ilFileDelivery::deliverFileAttached($tmp_name, $a_file_name, $a_mime_type, true);
     }
 
     /**
      * Save workbook to file
-     *
-     * @throws \PhpOffice\PhpSpreadsheet\Writer\Exception
      */
     public function writeToFile(string $a_file): void
     {
         $a_file = $this->prepareStorage($a_file);
 
-        $writer = IOFactory::createWriter($this->workbook, $this->format);
-        $writer->save($a_file);
+        try {
+            IOFactory::createWriter($this->workbook, $this->format)->save($a_file);
+        } catch (SpreadsheetException $e) {
+            throw new ilException($e->getMessage());
+        }
     }
 
-    /**
-     * @throws \PhpOffice\PhpSpreadsheet\Writer\Exception
-     */
     public function writeToTmpFile(): string
     {
-        $writer = IOFactory::createWriter($this->workbook, $this->format);
         $filename = ilFileUtils::ilTempnam();
-        $writer->save($filename);
+        try {
+            IOFactory::createWriter($this->workbook, $this->format)->save($filename);
+        } catch (SpreadsheetException $e) {
+            throw new ilException($e->getMessage());
+        }
 
         return $filename;
     }
@@ -559,16 +574,17 @@ public function getCoordByColumnAndRow(
         return $columnLetter . $pRow;
     }
 
-    /**
-     * @throws \PhpOffice\PhpSpreadsheet\Exception
-     */
     public function addLink(
         int $a_row,
         int $a_column,
         string $a_path
     ): void {
         $coordinate = $this->getCoordByColumnAndRow($a_column, $a_row);
-        $this->workbook->getActiveSheet()->getCell($coordinate)->getHyperlink()->setUrl($a_path);
+        try {
+            $this->workbook->getActiveSheet()->getCell($coordinate)->getHyperlink()->setUrl($a_path);
+        } catch (SpreadsheetException $e) {
+            throw new ilException($e->getMessage());
+        }
     }
 
     /**
@@ -582,11 +598,14 @@ public function columnIndexAdjustment(int $column): int
 
     /**
      * @param string $coordinatesRange A coordinates range string like 'A1:B5'
-     * @throws \PhpOffice\PhpSpreadsheet\Exception
      */
     public function mergeCells(string $coordinatesRange): void
     {
-        $this->workbook->getActiveSheet()->mergeCells($coordinatesRange);
+        try {
+            $this->workbook->getActiveSheet()->mergeCells($coordinatesRange);
+        } catch (SpreadsheetException $e) {
+            throw new ilException($e->getMessage());
+        }
     }
 
     private function cleanupNonCharachters(string $string): string

components/ILIAS/Excel/src/CellType.php

@@ -0,0 +1,32 @@
+<?php
+
+/**
+ * This file is part of ILIAS, a powerful learning management system
+ * published by ILIAS open source e-Learning e.V.
+ *
+ * ILIAS is licensed with the GPL-3.0,
+ * see https://www.gnu.org/licenses/gpl-3.0.en.html
+ * You should have received a copy of said license along with the
+ * source code, too.
+ *
+ * If this is not the case or you just want to try ILIAS, you'll find
+ * us at:
+ * https://www.ilias.de
+ * https://github.com/ILIAS-eLearning
+ *
+ *********************************************************************/
+
+declare(strict_types=1);
+
+namespace ILIAS\Excel;
+
+/**
+ * Explicit data type of a cell, see {@see \ilExcel::setCell()}.
+ */
+enum CellType: string
+{
+    case STRING = 's';
+    case NUMERIC = 'n';
+    case BOOL = 'b';
+    case FORMULA = 'f';
+}

components/ILIAS/Excel/tests/ExcelTestTBD.php → components/ILIAS/Excel/tests/ExcelTest.php

@@ -63,4 +63,22 @@ public function testCoordByColumnAndRow(): void
             $excel->getCoordByColumnAndRow(2, 2)
         );
     }
+
+    public function testExceptionsOfTheLibraryAreTranslated(): void
+    {
+        $excel = new ilExcel();
+        $excel->addSheet('first');
+
+        $this->expectException(ilException::class);
+        $excel->setActiveSheet(5);
+    }
+
+    public function testExplicitStringDataTypeKeepsNumericText(): void
+    {
+        $excel = new ilExcel();
+        $excel->addSheet('first');
+        $excel->setCell(1, 0, '007', \ILIAS\Excel\CellType::STRING);
+
+        $this->assertSame('007', $excel->getCell(1, 0));
+    }
 }

components/ILIAS/Exercise/classes/BackgroundTasks/class.ilExerciseManagementCollectFilesJob.php

@@ -113,7 +113,6 @@ public function isStateless(): bool
     /**
      * run the job
      * @throws \ILIAS\BackgroundTasks\Exceptions\InvalidArgumentException
-     * @throws \PhpOffice\PhpSpreadsheet\Exception
      * @throws ilDatabaseException
      * @throws ilExerciseException
      * @throws ilObjectNotFoundException
@@ -186,7 +185,6 @@ public function getExpectedTimeOfTaskInSeconds(): int
 
     /**
      * Set the Excel column titles.
-     * @throws \PhpOffice\PhpSpreadsheet\Exception
      */
     protected function addColumnTitles(): void
     {
@@ -282,7 +280,6 @@ protected function isExcelNeeded(int $a_ass_type, bool $a_has_fbk): bool
 
     /**
      * Add criteria data to the excel.
-     * @throws \PhpOffice\PhpSpreadsheet\Exception
      */
     protected function addCriteriaToExcel(
         int $feedback_giver,
@@ -442,7 +439,6 @@ public function addLink(
      * write assignment data to excel file
      * @todo Refactoring needed, long method...
      * @param int $assignment_id
-     * @throws \PhpOffice\PhpSpreadsheet\Exception
      * @throws ilDatabaseException
      * @throws ilExerciseException
      * @throws ilObjectNotFoundException
@@ -483,7 +479,7 @@ protected function collectAssignmentData(int $assignment_id): void
         }
 
         if ($this->isExcelNeeded($assignment_type, $ass_has_feedback)) {
-            // PhpSpreadsheet object
+            // spreadsheet
             $this->excel = new ilExcel();
 
             //Excel sheet title

components/ILIAS/Exercise/classes/class.ilObjExercise.php

@@ -614,7 +614,6 @@ public function updateAllUsersStatus(): void
 
     /**
      * Exports grades as excel
-     * @throws \PhpOffice\PhpSpreadsheet\Exception
      * @throws ilExcUnknownAssignmentTypeException
      */
     public function exportGradesExcel(): void

components/ILIAS/Survey/Evaluation/class.ilSurveyEvaluationGUI.php

@@ -425,7 +425,6 @@ public function exportCumulatedResults(
     /**
      * Export details (excel only)
      * @param ilSurveyEvaluationResults|array $a_results
-     * @throws \PhpOffice\PhpSpreadsheet\Exception
      */
     protected function exportResultsDetailsExcel(
         ilExcel $a_excel,

components/ILIAS/Test/src/ExportImport/ResultsExportExcel.php

@@ -22,7 +22,6 @@
 
 use ILIAS\TestQuestionPool\Questions\GeneralQuestionPropertiesRepository;
 use ILIAS\Data\DateFormat\DateFormat;
-use PhpOffice\PhpSpreadsheet\Cell\DataType;
 
 /**
  * @author Fabian Helfer <fhelfer@databay.de>
@@ -129,9 +128,6 @@ public function write(): ?string
         return $path;
     }
 
-    /**
-     * @throws \PhpOffice\PhpSpreadsheet\Writer\Exception
-     */
     public function deliver(): void
     {
         $this->worksheet->sendToClient($this->filename);