Skip to content

Commit a7378be

Browse files
oleibmanoleibman
committed
Better Definitions for Mixed Parameters and Values Part 2 of Many
Continuing work started with PR #4019. Improve documentation within program by making explicit what types of values are allowed for variables described as "mixed". In order to avoid broken functionality, this is done mainly through doc-blocks. This will get us closer to Phpstan Level 9, but many changes will be needed before we can consider that. This change has more executable code changes than its predecessor. I will wait longer than normal before merging it to allow for additional testing.
1 parent 563de5f commit a7378be

File tree

20 files changed

+104
-62
lines changed

20 files changed

+104
-62
lines changed

‎src/PhpSpreadsheet/Collection/Cells.php

+12-6
Original file line numberDiff line numberDiff line change
@@ -288,7 +288,7 @@ public function cloneCellCollection(Worksheet $worksheet): static
288288
$newCollection->index[$key] = $value;
289289
$stored = $newCollection->cache->set(
290290
$newCollection->cachePrefix . $key,
291-
clone $this->cache->get($this->cachePrefix . $key)
291+
clone $this->getCache($key)
292292
);
293293
if ($stored === false) {
294294
$this->destructIfNeeded($newCollection, 'Failed to copy cells in cache');
@@ -410,11 +410,7 @@ public function get(string $cellCoordinate): ?Cell
410410
return null;
411411
}
412412

413-
// Check if the entry that has been requested actually exists in the cache
414-
$cell = $this->cache->get($this->cachePrefix . $cellCoordinate);
415-
if ($cell === null) {
416-
throw new PhpSpreadsheetException("Cell entry {$cellCoordinate} no longer exists in cache. This probably means that the cache was cleared by someone else.");
417-
}
413+
$cell = $this->getcache($cellCoordinate);
418414

419415
// Set current entry to the requested entry
420416
$this->currentCoordinate = $cellCoordinate;
@@ -466,4 +462,14 @@ private function getAllCacheKeys(): iterable
466462
yield $this->cachePrefix . $coordinate;
467463
}
468464
}
465+
466+
private function getCache(string $cellCoordinate): Cell
467+
{
468+
$cell = $this->cache->get($this->cachePrefix . $cellCoordinate);
469+
if (!($cell instanceof Cell)) {
470+
throw new PhpSpreadsheetException("Cell entry {$cellCoordinate} no longer exists in cache. This probably means that the cache was cleared by someone else.");
471+
}
472+
473+
return $cell;
474+
}
469475
}

‎src/PhpSpreadsheet/Helper/Html.php

+2
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
namespace PhpOffice\PhpSpreadsheet\Helper;
44

5+
use DOMAttr;
56
use DOMDocument;
67
use DOMElement;
78
use DOMNode;
@@ -708,6 +709,7 @@ protected function startFontTag(DOMElement $tag): void
708709
{
709710
$attrs = $tag->attributes;
710711
if ($attrs !== null) {
712+
/** @var DOMAttr $attribute */
711713
foreach ($attrs as $attribute) {
712714
$attributeName = strtolower($attribute->name);
713715
$attributeName = preg_replace('/^html:/', '', $attributeName) ?? $attributeName; // in case from Xml spreadsheet

‎src/PhpSpreadsheet/Helper/Sample.php

+4-8
Original file line numberDiff line numberDiff line change
@@ -81,13 +81,9 @@ public function getSamples(): array
8181
$regex = new RegexIterator($iterator, '/^.+\.php$/', RecursiveRegexIterator::GET_MATCH);
8282

8383
$files = [];
84+
/** @var string[] $file */
8485
foreach ($regex as $file) {
8586
$file = str_replace(str_replace('\\', '/', $baseDir) . '/', '', str_replace('\\', '/', $file[0]));
86-
if (is_array($file)) {
87-
// @codeCoverageIgnoreStart
88-
throw new RuntimeException('str_replace returned array');
89-
// @codeCoverageIgnoreEnd
90-
}
9187
$info = pathinfo($file);
9288
$category = str_replace('_', ' ', $info['dirname'] ?? '');
9389
$name = str_replace('_', ' ', (string) preg_replace('/(|\.php)/', '', $info['filename']));
@@ -254,10 +250,10 @@ public function logCalculationResult(
254250
?string $descriptionCell = null
255251
): void {
256252
if ($descriptionCell !== null) {
257-
$this->log($worksheet->getCell($descriptionCell)->getValue());
253+
$this->log($worksheet->getCell($descriptionCell)->getValueString());
258254
}
259-
$this->log($worksheet->getCell($formulaCell)->getValue());
260-
$this->log(sprintf('%s() Result is ', $functionName) . $worksheet->getCell($formulaCell)->getCalculatedValue());
255+
$this->log($worksheet->getCell($formulaCell)->getValueString());
256+
$this->log(sprintf('%s() Result is ', $functionName) . $worksheet->getCell($formulaCell)->getCalculatedValueString());
261257
}
262258

263259
/**

‎src/PhpSpreadsheet/Reader/Html.php

+2
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
namespace PhpOffice\PhpSpreadsheet\Reader;
44

5+
use DOMAttr;
56
use DOMDocument;
67
use DOMElement;
78
use DOMNode;
@@ -291,6 +292,7 @@ protected function flushCell(Worksheet $sheet, string $column, int|string $row,
291292
private function processDomElementBody(Worksheet $sheet, int &$row, string &$column, string &$cellContent, DOMElement $child): void
292293
{
293294
$attributeArray = [];
295+
/** @var DOMAttr $attribute */
294296
foreach ($child->attributes as $attribute) {
295297
$attributeArray[$attribute->name] = $attribute->value;
296298
}

‎src/PhpSpreadsheet/Reader/Slk.php

+2
Original file line numberDiff line numberDiff line change
@@ -268,6 +268,7 @@ private function processCRecord(array $rowData, Spreadsheet &$spreadsheet, strin
268268
if ($sharedFormula === true && $sharedRow >= 0 && $sharedColumn >= 0) {
269269
$thisCoordinate = Coordinate::stringFromColumnIndex((int) $column) . $row;
270270
$sharedCoordinate = Coordinate::stringFromColumnIndex($sharedColumn) . $sharedRow;
271+
/** @var string */
271272
$formula = $spreadsheet->getActiveSheet()->getCell($sharedCoordinate)->getValue();
272273
$spreadsheet->getActiveSheet()->getCell($thisCoordinate)->setValue($formula);
273274
$referenceHelper = ReferenceHelper::getInstance();
@@ -281,6 +282,7 @@ private function processCRecord(array $rowData, Spreadsheet &$spreadsheet, strin
281282
return;
282283
}
283284
$columnLetter = Coordinate::stringFromColumnIndex((int) $column);
285+
/** @var string */
284286
$cellData = Calculation::unwrapResult($cellData);
285287

286288
// Set cell value

‎src/PhpSpreadsheet/Shared/Escher/DgContainer/SpgrContainer.php

+2
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ public function getParent(): ?self
3232

3333
/**
3434
* Add a child. This will be either spgrContainer or spContainer.
35+
*
36+
* @param SpgrContainer|SpgrContainer\SpContainer $child child to be added
3537
*/
3638
public function addChild(mixed $child): void
3739
{

‎src/PhpSpreadsheet/Spreadsheet.php

+1-1
Original file line numberDiff line numberDiff line change
@@ -253,7 +253,7 @@ public function discardMacros(): void
253253
*/
254254
public function setRibbonXMLData(mixed $target, mixed $xmlData): void
255255
{
256-
if ($target !== null && $xmlData !== null) {
256+
if (is_string($target) && is_string($xmlData)) {
257257
$this->ribbonXMLData = ['target' => $target, 'data' => $xmlData];
258258
} else {
259259
$this->ribbonXMLData = null;

‎src/PhpSpreadsheet/Style/ConditionalFormatting/CellMatcher.php

+1-1
Original file line numberDiff line numberDiff line change
@@ -235,7 +235,7 @@ protected function processDuplicatesComparison(Conditional $conditional): bool
235235
self::COMPARISON_DUPLICATES_OPERATORS[$conditional->getConditionType()],
236236
$worksheetName,
237237
$this->conditionalRange,
238-
$this->cellConditionCheck($this->cell->getCalculatedValue())
238+
$this->cellConditionCheck($this->cell->getCalculatedValueString())
239239
);
240240

241241
return $this->evaluateExpression($expression);

‎src/PhpSpreadsheet/Style/ConditionalFormatting/Wizard/CellValue.php

+4-1
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@ protected function operand(int $index, mixed $operand, string $operandValueType
6969
$this->operandValueType[$index] = $operandValueType;
7070
}
7171

72+
/** @param null|bool|float|int|string $value value to be wrapped */
7273
protected function wrapValue(mixed $value, string $operandValueType): float|int|string
7374
{
7475
if (!is_numeric($value) && !is_bool($value) && null !== $value) {
@@ -175,7 +176,9 @@ public function __call(string $methodName, array $arguments): self
175176
if (count($arguments) < 2) {
176177
$this->operand(0, $arguments[0]);
177178
} else {
178-
$this->operand(0, $arguments[0], $arguments[1]);
179+
/** @var string */
180+
$arg1 = $arguments[1];
181+
$this->operand(0, $arguments[0], $arg1);
179182
}
180183

181184
return $this;

‎src/PhpSpreadsheet/Style/ConditionalFormatting/Wizard/Expression.php

+1-1
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ public static function fromConditional(Conditional $conditional, string $cellRan
5454
}
5555

5656
/**
57-
* @param mixed[] $arguments
57+
* @param string[] $arguments
5858
*/
5959
public function __call(string $methodName, array $arguments): self
6060
{

‎src/PhpSpreadsheet/Style/ConditionalFormatting/Wizard/TextValue.php

+8-2
Original file line numberDiff line numberDiff line change
@@ -148,9 +148,15 @@ public function __call(string $methodName, array $arguments): self
148148
$this->operator(self::MAGIC_OPERATIONS[$methodName]);
149149
//$this->operand(...$arguments);
150150
if (count($arguments) < 2) {
151-
$this->operand($arguments[0]);
151+
/** @var string */
152+
$arg0 = $arguments[0];
153+
$this->operand($arg0);
152154
} else {
153-
$this->operand($arguments[0], $arguments[1]);
155+
/** @var string */
156+
$arg0 = $arguments[0];
157+
/** @var string */
158+
$arg1 = $arguments[1];
159+
$this->operand($arg0, $arg1);
154160
}
155161

156162
return $this;

‎src/PhpSpreadsheet/Style/NumberFormat/DateFormatter.php

+1
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,7 @@ private static function tryInterval(bool &$seekingBracket, string &$block, mixed
115115
}
116116
}
117117

118+
/** @param float|int $value value to be formatted */
118119
public static function format(mixed $value, string $format): string
119120
{
120121
// strip off first part containing e.g. [$-F800] or [$USD-409]

‎src/PhpSpreadsheet/Style/NumberFormat/NumberFormatter.php

+1
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,7 @@ private static function formatStraightNumericValue(mixed $value, string $format,
185185
return self::pregReplace(self::NUMBER_REGEX, $value, $format);
186186
}
187187

188+
/** @param float|int|numeric-string $value value to be formatted */
188189
public static function format(mixed $value, string $format): string
189190
{
190191
// The "_" in this string has already been stripped out,

‎src/PhpSpreadsheet/Worksheet/AutoFilter.php

+12-6
Original file line numberDiff line numberDiff line change
@@ -309,7 +309,7 @@ public function shiftColumn(string $fromColumn, string $toColumn): static
309309
/**
310310
* Test if cell value is in the defined set of values.
311311
*
312-
* @param mixed[] $dataSet
312+
* @param array{blanks: bool, filterValues: array<string,array<string,string>>} $dataSet
313313
*/
314314
protected static function filterTestInSimpleDataSet(mixed $cellValue, array $dataSet): bool
315315
{
@@ -325,7 +325,7 @@ protected static function filterTestInSimpleDataSet(mixed $cellValue, array $dat
325325
/**
326326
* Test if cell value is in the defined set of Excel date values.
327327
*
328-
* @param mixed[] $dataSet
328+
* @param array{blanks: bool, filterValues: array<string,array<string,string>>} $dataSet
329329
*/
330330
protected static function filterTestInDateGroupSet(mixed $cellValue, array $dataSet): bool
331331
{
@@ -763,9 +763,13 @@ private function calculateTopTenValue(string $columnID, int $startRow, int $endR
763763
sort($dataValues);
764764
}
765765

766-
$slice = array_slice($dataValues, 0, $ruleValue);
767-
768-
$retVal = array_pop($slice);
766+
if (is_numeric($ruleValue)) {
767+
$ruleValue = (int) $ruleValue;
768+
}
769+
if ($ruleValue === null || is_int($ruleValue)) {
770+
$slice = array_slice($dataValues, 0, $ruleValue);
771+
$retVal = array_pop($slice);
772+
}
769773
}
770774

771775
return $retVal;
@@ -968,7 +972,7 @@ public function showHideRows(): static
968972
$ruleOperator = $rule->getOperator();
969973
}
970974
if (is_numeric($ruleValue) && $ruleOperator === Rule::AUTOFILTER_COLUMN_RULE_TOPTEN_PERCENT) {
971-
$ruleValue = floor((float) $ruleValue * ($dataRowCount / 100));
975+
$ruleValue = (int) floor((float) $ruleValue * ($dataRowCount / 100));
972976
}
973977
if (!is_array($ruleValue) && $ruleValue < 1) {
974978
$ruleValue = 1;
@@ -977,6 +981,7 @@ public function showHideRows(): static
977981
$ruleValue = 500;
978982
}
979983

984+
/** @var float|int|string */
980985
$maxVal = $this->calculateTopTenValue($columnID, $rangeStart[1] + 1, (int) $rangeEnd[1], $toptenRuleType, $ruleValue);
981986

982987
$operator = ($toptenRuleType == Rule::AUTOFILTER_COLUMN_RULE_TOPTEN_TOP)
@@ -1003,6 +1008,7 @@ public function showHideRows(): static
10031008
// Execute the filter test
10041009
/** @var callable */
10051010
$temp = [self::class, $columnFilterTest['method']];
1011+
/** @var bool */
10061012
$result // $result && // phpstan says $result is always true here
10071013
= call_user_func_array($temp, [$cellValue, $columnFilterTest['arguments']]);
10081014
// If filter test has resulted in FALSE, exit the loop straightaway rather than running any more tests

‎src/PhpSpreadsheet/Worksheet/AutoFilter/Column.php

+6-5
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ class Column
7676
/**
7777
* Autofilter Column Dynamic Attributes.
7878
*
79-
* @var mixed[]
79+
* @var (float|int|string)[]
8080
*/
8181
private array $attributes = [];
8282

@@ -209,7 +209,7 @@ public function setJoin(string $join): static
209209
/**
210210
* Set AutoFilter Attributes.
211211
*
212-
* @param mixed[] $attributes
212+
* @param (float|int|string)[] $attributes
213213
*
214214
* @return $this
215215
*/
@@ -225,7 +225,7 @@ public function setAttributes(array $attributes): static
225225
* Set An AutoFilter Attribute.
226226
*
227227
* @param string $name Attribute Name
228-
* @param int|string $value Attribute Value
228+
* @param float|int|string $value Attribute Value
229229
*
230230
* @return $this
231231
*/
@@ -240,7 +240,7 @@ public function setAttribute(string $name, $value): static
240240
/**
241241
* Get AutoFilter Column Attributes.
242242
*
243-
* @return int[]|string[]
243+
* @return (float|int|string)[]
244244
*/
245245
public function getAttributes(): array
246246
{
@@ -252,7 +252,7 @@ public function getAttributes(): array
252252
*
253253
* @param string $name Attribute Name
254254
*/
255-
public function getAttribute(string $name): null|int|string
255+
public function getAttribute(string $name): null|float|int|string
256256
{
257257
if (isset($this->attributes[$name])) {
258258
return $this->attributes[$name];
@@ -360,6 +360,7 @@ public function clearRules(): static
360360
public function __clone()
361361
{
362362
$vars = get_object_vars($this);
363+
/** @var AutoFilter\Column\Rule[] $value */
363364
foreach ($vars as $key => $value) {
364365
if ($key === 'parent') {
365366
// Detach from autofilter parent

‎src/PhpSpreadsheet/Worksheet/Worksheet.php

+12-7
Original file line numberDiff line numberDiff line change
@@ -745,7 +745,7 @@ public function calculateColumnWidths(): static
745745
// Calculated value
746746
// To formatted string
747747
$cellValue = NumberFormat::toFormattedString(
748-
$cell->getCalculatedValue(),
748+
$cell->getCalculatedValueString(),
749749
(string) $this->getParentOrThrow()->getCellXfByIndex($cell->getXfIndex())
750750
->getNumberFormat()->getFormatCode(true)
751751
);
@@ -2795,6 +2795,8 @@ public function fromArray(array $source, mixed $nullValue = null, string $startC
27952795
}
27962796

27972797
/**
2798+
* @param null|bool|float|int|RichText|string $nullValue value to use when null
2799+
*
27982800
* @throws Exception
27992801
* @throws \PhpOffice\PhpSpreadsheet\Calculation\Exception
28002802
*/
@@ -2811,8 +2813,10 @@ protected function cellToArray(Cell $cell, bool $calculateFormulas, bool $format
28112813

28122814
if ($formatData) {
28132815
$style = $this->getParentOrThrow()->getCellXfByIndex($cell->getXfIndex());
2816+
/** @var null|bool|float|int|RichText|string */
2817+
$returnValuex = $returnValue;
28142818
$returnValue = NumberFormat::toFormattedString(
2815-
$returnValue,
2819+
$returnValuex,
28162820
$style->getNumberFormat()->getFormatCode() ?? NumberFormat::FORMAT_GENERAL
28172821
);
28182822
}
@@ -2824,7 +2828,7 @@ protected function cellToArray(Cell $cell, bool $calculateFormulas, bool $format
28242828
/**
28252829
* Create array from a range of cells.
28262830
*
2827-
* @param mixed $nullValue Value returned in the array entry if a cell doesn't exist
2831+
* @param null|bool|float|int|RichText|string $nullValue Value returned in the array entry if a cell doesn't exist
28282832
* @param bool $calculateFormulas Should formulas be calculated?
28292833
* @param bool $formatData Should formatting be applied to cell values?
28302834
* @param bool $returnCellRef False - Return a simple array of rows and columns indexed by number counting from zero
@@ -2854,7 +2858,7 @@ public function rangeToArray(
28542858
/**
28552859
* Create array from a range of cells, yielding each row in turn.
28562860
*
2857-
* @param mixed $nullValue Value returned in the array entry if a cell doesn't exist
2861+
* @param null|bool|float|int|RichText|string $nullValue Value returned in the array entry if a cell doesn't exist
28582862
* @param bool $calculateFormulas Should formulas be calculated?
28592863
* @param bool $formatData Should formatting be applied to cell values?
28602864
* @param bool $returnCellRef False - Return a simple array of rows and columns indexed by number counting from zero
@@ -3002,7 +3006,7 @@ private function validateNamedRange(string $definedName, bool $returnNullIfInval
30023006
* Create array from a range of cells.
30033007
*
30043008
* @param string $definedName The Named Range that should be returned
3005-
* @param mixed $nullValue Value returned in the array entry if a cell doesn't exist
3009+
* @param null|bool|float|int|RichText|string $nullValue Value returned in the array entry if a cell doesn't exist
30063010
* @param bool $calculateFormulas Should formulas be calculated?
30073011
* @param bool $formatData Should formatting be applied to cell values?
30083012
* @param bool $returnCellRef False - Return a simple array of rows and columns indexed by number counting from zero
@@ -3035,7 +3039,7 @@ public function namedRangeToArray(
30353039
/**
30363040
* Create array from worksheet.
30373041
*
3038-
* @param mixed $nullValue Value returned in the array entry if a cell doesn't exist
3042+
* @param null|bool|float|int|RichText|string $nullValue Value returned in the array entry if a cell doesn't exist
30393043
* @param bool $calculateFormulas Should formulas be calculated?
30403044
* @param bool $formatData Should formatting be applied to cell values?
30413045
* @param bool $returnCellRef False - Return a simple array of rows and columns indexed by number counting from zero
@@ -3650,13 +3654,14 @@ public function copyCells(string $fromCell, string $toCells, bool $copyStyle = t
36503654
{
36513655
$toArray = Coordinate::extractAllCellReferencesInRange($toCells);
36523656
$value = $this->getCell($fromCell)->getValue();
3657+
$valueString = $this->getCell($fromCell)->getValueString();
36533658
$style = $this->getStyle($fromCell)->exportArray();
36543659
$fromIndexes = Coordinate::indexesFromString($fromCell);
36553660
$referenceHelper = ReferenceHelper::getInstance();
36563661
foreach ($toArray as $destination) {
36573662
if ($destination !== $fromCell) {
36583663
$toIndexes = Coordinate::indexesFromString($destination);
3659-
$this->getCell($destination)->setValue($referenceHelper->updateFormulaReferences($value, 'A1', $toIndexes[0] - $fromIndexes[0], $toIndexes[1] - $fromIndexes[1]));
3664+
$this->getCell($destination)->setValue($referenceHelper->updateFormulaReferences($valueString, 'A1', $toIndexes[0] - $fromIndexes[0], $toIndexes[1] - $fromIndexes[1]));
36603665
if ($copyStyle) {
36613666
$this->getCell($destination)->getStyle()->applyFromArray($style);
36623667
}

0 commit comments

Comments
 (0)