Narrow DOMDocument::createElement() return type and throw type for valid constant names

src/Type/Php/DomDocumentCreateElementDynamicReturnTypeExtension.php

@@ -0,0 +1,63 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Type\Php;
+
+use DOMDocument;
+use DOMException;
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\DependencyInjection\AutowiredService;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Reflection\ParametersAcceptorSelector;
+use PHPStan\Type\Constant\ConstantBooleanType;
+use PHPStan\Type\DynamicMethodReturnTypeExtension;
+use PHPStan\Type\NeverType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+use function extension_loaded;
+
+#[AutowiredService]
+final class DomDocumentCreateElementDynamicReturnTypeExtension implements DynamicMethodReturnTypeExtension
+{
+
+	public function getClass(): string
+	{
+		return DOMDocument::class;
+	}
+
+	public function isMethodSupported(MethodReflection $methodReflection): bool
+	{
+		return extension_loaded('dom') && $methodReflection->getName() === 'createElement';
+	}
+
+	public function getTypeFromMethodCall(MethodReflection $methodReflection, MethodCall $methodCall, Scope $scope): ?Type
+	{
+		$args = $methodCall->getArgs();
+		if (!isset($args[0])) {
+			return null;
+		}
+
+		$argType = $scope->getType($args[0]->value);
+
+		$doc = new DOMDocument();
+
+		foreach ($argType->getConstantStrings() as $constantString) {
+			try {
+				$doc->createElement($constantString->getValue());
+			} catch (DOMException) {
+				return null;
+			}
+
+			$argType = TypeCombinator::remove($argType, $constantString);
+		}
+
+		if (!$argType instanceof NeverType) {
+			return null;
+		}
+
+		$variant = ParametersAcceptorSelector::selectFromArgs($scope, $args, $methodReflection->getVariants());
+
+		return TypeCombinator::remove($variant->getReturnType(), new ConstantBooleanType(false));
+	}
+
+}

src/Type/Php/DomDocumentCreateElementDynamicThrowTypeExtension.php

@@ -0,0 +1,57 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Type\Php;
+
+use DOMDocument;
+use DOMException;
+use PhpParser\Node\Expr\MethodCall;
+use PHPStan\Analyser\Scope;
+use PHPStan\DependencyInjection\AutowiredService;
+use PHPStan\Reflection\MethodReflection;
+use PHPStan\Type\DynamicMethodThrowTypeExtension;
+use PHPStan\Type\NeverType;
+use PHPStan\Type\ObjectType;
+use PHPStan\Type\Type;
+use PHPStan\Type\TypeCombinator;
+use function extension_loaded;
+
+#[AutowiredService]
+final class DomDocumentCreateElementDynamicThrowTypeExtension implements DynamicMethodThrowTypeExtension
+{
+
+	public function isMethodSupported(MethodReflection $methodReflection): bool
+	{
+		return extension_loaded('dom')
+			&& $methodReflection->getDeclaringClass()->getName() === DOMDocument::class
+			&& $methodReflection->getName() === 'createElement';
+	}
+
+	public function getThrowTypeFromMethodCall(MethodReflection $methodReflection, MethodCall $methodCall, Scope $scope): ?Type
+	{
+		$args = $methodCall->getArgs();
+		if (!isset($args[0])) {
+			return new ObjectType(DOMException::class);
+		}
+
+		$argType = $scope->getType($args[0]->value);
+
+		$doc = new DOMDocument();
+
+		foreach ($argType->getConstantStrings() as $constantString) {
+			try {
+				$doc->createElement($constantString->getValue());
+			} catch (DOMException) {
+				return new ObjectType(DOMException::class);
+			}
+
+			$argType = TypeCombinator::remove($argType, $constantString);
+		}
+
+		if (!$argType instanceof NeverType) {
+			return new ObjectType(DOMException::class);
+		}
+
+		return null;
+	}
+
+}

tests/PHPStan/Analyser/nsrt/dom-document-create-element.php

@@ -0,0 +1,48 @@
+<?php declare(strict_types = 1);
+
+namespace DomDocumentCreateElement;
+
+use DOMDocument;
+use function PHPStan\Testing\assertType;
+
+class Foo
+{
+
+	public function dynamicName(DOMDocument $doc, string $name): void
+	{
+		assertType('(DOMElement|false)', $doc->createElement($name));
+	}
+
+	public function validConstantNames(DOMDocument $doc): void
+	{
+		assertType('DOMElement', $doc->createElement('div'));
+		assertType('DOMElement', $doc->createElement('my-element'));
+		assertType('DOMElement', $doc->createElement('ns:tag'));
+		assertType('DOMElement', $doc->createElement('_private'));
+		assertType('DOMElement', $doc->createElement('h1'));
+	}
+
+	public function invalidConstantNames(DOMDocument $doc): void
+	{
+		assertType('(DOMElement|false)', $doc->createElement(''));
+		assertType('(DOMElement|false)', $doc->createElement('123element'));
+		assertType('(DOMElement|false)', $doc->createElement('my element'));
+	}
+
+	/**
+	 * @param 'div'|'span' $validUnion
+	 * @param 'div'|'' $mixedUnion
+	 */
+	public function unions(DOMDocument $doc, string $validUnion, string $mixedUnion): void
+	{
+		assertType('DOMElement', $doc->createElement($validUnion));
+		assertType('(DOMElement|false)', $doc->createElement($mixedUnion));
+	}
+
+	public function localVariable(DOMDocument $doc): void
+	{
+		$name = 'paragraph';
+		assertType('DOMElement', $doc->createElement($name));
+	}
+
+}

tests/PHPStan/Rules/Exceptions/MissingCheckedExceptionInMethodThrowsRuleTest.php

@@ -67,6 +67,10 @@ public function testRule(): void
 				122,
 			];
 		}
+		$errors[] = [
+			'Method MissingExceptionMethodThrows\Foo::domCreateElementDoesThrow() throws checked exception DOMException but it\'s missing from the PHPDoc @throws tag.',
+			133,
+		];
 		$this->analyse([__DIR__ . '/data/missing-exception-method-throws.php'], $errors);
 	}
 

tests/PHPStan/Rules/Exceptions/data/missing-exception-method-throws.php

@@ -122,4 +122,15 @@ public function dateTimeModifyDoesThrows(\DateTime $dt, \DateTimeImmutable $dti,
 		$dti->modify($m);
 	}
 
+	public function domCreateElementDoesNotThrow(\DOMDocument $doc): void
+	{
+		$doc->createElement('div');
+		$doc->createElement('my-element');
+	}
+
+	public function domCreateElementDoesThrow(\DOMDocument $doc, string $name): void
+	{
+		$doc->createElement($name);
+	}
+
 }