Add array-shape return type for localeconv() and shape-based localtime() return type extension (phpstan#6031)

Co-authored-by: VincentLanglet <9052536+VincentLanglet@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

resources/functionMap.php

@@ -5449,7 +5449,7 @@
 'locale_lookup' => ['string|null', 'langtag'=>'array', 'locale'=>'string', 'canonicalize='=>'bool', 'defaultLocale='=>'string'],
 'locale_parse' => ['array|null', 'locale'=>'string'],
 'locale_set_default' => ['bool', 'locale'=>'string'],
-'localeconv' => ['array'],
+'localeconv' => ['array{decimal_point: string, thousands_sep: string, int_curr_symbol: string, currency_symbol: string, mon_decimal_point: string, mon_thousands_sep: string, positive_sign: string, negative_sign: string, int_frac_digits: int, frac_digits: int, p_cs_precedes: int, p_sep_by_space: int, n_cs_precedes: int, n_sep_by_space: int, p_sign_posn: int, n_sign_posn: int, grouping: list<int>, mon_grouping: array<int, int>}'],
 'localtime' => ['array', 'timestamp='=>'int', 'associative_array='=>'bool'],
 'log' => ['float', 'number'=>'float', 'base='=>'float'],
 'log10' => ['float', 'number'=>'float'],

src/Type/Php/LocaltimeFunctionDynamicReturnTypeExtension.php

@@ -0,0 +1,86 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Type\Php;
+
+use PhpParser\Node\Expr\FuncCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\DependencyInjection\AutowiredService;
+use PHPStan\Reflection\FunctionReflection;
+use PHPStan\Type\Constant\ConstantArrayTypeBuilder;
+use PHPStan\Type\Constant\ConstantBooleanType;
+use PHPStan\Type\Constant\ConstantStringType;
+use PHPStan\Type\DynamicFunctionReturnTypeExtension;
+use PHPStan\Type\IntegerRangeType;
+use PHPStan\Type\IntegerType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+use function count;
+
+#[AutowiredService]
+final class LocaltimeFunctionDynamicReturnTypeExtension implements DynamicFunctionReturnTypeExtension
+{
+
+	public function isFunctionSupported(FunctionReflection $functionReflection): bool
+	{
+		return $functionReflection->getName() === 'localtime';
+	}
+
+	public function getTypeFromFunctionCall(FunctionReflection $functionReflection, FuncCall $functionCall, Scope $scope): Type
+	{
+		$args = $functionCall->getArgs();
+
+		$associativeType = count($args) >= 2 ? $scope->getType($args[1]->value)->toBoolean() : new ConstantBooleanType(false);
+
+		if ($associativeType->isTrue()->yes()) {
+			return $this->createAssociativeType();
+		}
+
+		if ($associativeType->isFalse()->yes()) {
+			return $this->createListType();
+		}
+
+		return TypeCombinator::union($this->createListType(), $this->createAssociativeType());
+	}
+
+	private function createListType(): Type
+	{
+		$builder = ConstantArrayTypeBuilder::createEmpty();
+		foreach ($this->createFieldTypes() as [, $valueType]) {
+			$builder->setOffsetValueType(null, $valueType);
+		}
+
+		return $builder->getArray();
+	}
+
+	private function createAssociativeType(): Type
+	{
+		$builder = ConstantArrayTypeBuilder::createEmpty();
+		foreach ($this->createFieldTypes() as [$key, $valueType]) {
+			$builder->setOffsetValueType(new ConstantStringType($key), $valueType);
+		}
+
+		return $builder->getArray();
+	}
+
+	/**
+	 * Fields of the C localtime struct in order, with the value ranges documented at
+	 * https://www.php.net/manual/en/function.localtime.php
+	 *
+	 * @return list<array{string, Type}>
+	 */
+	private function createFieldTypes(): array
+	{
+		return [
+			['tm_sec', IntegerRangeType::fromInterval(0, 59)],
+			['tm_min', IntegerRangeType::fromInterval(0, 59)],
+			['tm_hour', IntegerRangeType::fromInterval(0, 23)],
+			['tm_mday', IntegerRangeType::fromInterval(1, 31)],
+			['tm_mon', IntegerRangeType::fromInterval(0, 11)],
+			['tm_year', new IntegerType()],
+			['tm_wday', IntegerRangeType::fromInterval(0, 6)],
+			['tm_yday', IntegerRangeType::fromInterval(0, 365)],
+			['tm_isdst', new IntegerType()],
+		];
+	}
+
+}

tests/PHPStan/Analyser/nsrt/localeconv.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace LocaleconvBug;
+
+use function localeconv;
+use function localtime;
+use function PHPStan\Testing\assertType;
+
+function (): void {
+	$conv = localeconv();
+
+	assertType('array{decimal_point: string, thousands_sep: string, int_curr_symbol: string, currency_symbol: string, mon_decimal_point: string, mon_thousands_sep: string, positive_sign: string, negative_sign: string, int_frac_digits: int, frac_digits: int, p_cs_precedes: int, p_sep_by_space: int, n_cs_precedes: int, n_sep_by_space: int, p_sign_posn: int, n_sign_posn: int, grouping: list<int>, mon_grouping: array<int, int>}', $conv);
+
+	assertType('string', $conv['thousands_sep']);
+	assertType('string', $conv['decimal_point']);
+	assertType('int', $conv['frac_digits']);
+	assertType('list<int>', $conv['grouping']);
+};
+
+function (int $timestamp, bool $assoc): void {
+	assertType('array{int<0, 59>, int<0, 59>, int<0, 23>, int<1, 31>, int<0, 11>, int, int<0, 6>, int<0, 365>, int}', localtime());
+	assertType('array{int<0, 59>, int<0, 59>, int<0, 23>, int<1, 31>, int<0, 11>, int, int<0, 6>, int<0, 365>, int}', localtime($timestamp));
+	assertType('array{int<0, 59>, int<0, 59>, int<0, 23>, int<1, 31>, int<0, 11>, int, int<0, 6>, int<0, 365>, int}', localtime($timestamp, false));
+	assertType('array{tm_sec: int<0, 59>, tm_min: int<0, 59>, tm_hour: int<0, 23>, tm_mday: int<1, 31>, tm_mon: int<0, 11>, tm_year: int, tm_wday: int<0, 6>, tm_yday: int<0, 365>, tm_isdst: int}', localtime($timestamp, true));
+	assertType('array{int<0, 59>, int<0, 59>, int<0, 23>, int<1, 31>, int<0, 11>, int, int<0, 6>, int<0, 365>, int}|array{tm_sec: int<0, 59>, tm_min: int<0, 59>, tm_hour: int<0, 23>, tm_mday: int<1, 31>, tm_mon: int<0, 11>, tm_year: int, tm_wday: int<0, 6>, tm_yday: int<0, 365>, tm_isdst: int}', localtime($timestamp, $assoc));
+};