PHPDoc tag @api-do-not-implement instead of list in BcUncoveredInterface

ondrejmirtes · ondrejmirtes · commit 43d502614f7a · 2026-02-11T10:15:13.000+01:00
diff --git a/src/Analyser/Scope.php b/src/Analyser/Scope.php
@@ -42,6 +42,7 @@
  * $x is of type Foo.
  *
  * @api
+ * @api-do-not-implement
  */
 interface Scope extends ClassMemberAccessAnswerer, NamespaceAnswerer
 {
diff --git a/src/Command/Output.php b/src/Command/Output.php
@@ -2,7 +2,10 @@
 
 namespace PHPStan\Command;
 
-/** @api */
+/**
+ * @api
+ * @api-do-not-implement
+ */
 interface Output
 {
 
diff --git a/src/Command/OutputStyle.php b/src/Command/OutputStyle.php
@@ -2,7 +2,10 @@
 
 namespace PHPStan\Command;
 
-/** @api */
+/**
+ * @api
+ * @api-do-not-implement
+ */
 interface OutputStyle
 {
 
diff --git a/src/DependencyInjection/Container.php b/src/DependencyInjection/Container.php
@@ -2,7 +2,10 @@
 
 namespace PHPStan\DependencyInjection;
 
-/** @api */
+/**
+ * @api
+ * @api-do-not-implement
+ */
 interface Container
 {
 
diff --git a/src/Node/ReturnStatementsNode.php b/src/Node/ReturnStatementsNode.php
@@ -7,7 +7,10 @@
 use PHPStan\Analyser\ImpurePoint;
 use PHPStan\Analyser\StatementResult;
 
-/** @api */
+/**
+ * @api
+ * @api-do-not-implement
+ */
 interface ReturnStatementsNode extends VirtualNode
 {
 
diff --git a/src/Node/VirtualNode.php b/src/Node/VirtualNode.php
@@ -4,7 +4,10 @@
 
 use PhpParser\Node;
 
-/** @api */
+/**
+ * @api
+ * @api-do-not-implement
+ */
 interface VirtualNode extends Node
 {
 
diff --git a/src/PhpDoc/Tag/TypedTag.php b/src/PhpDoc/Tag/TypedTag.php
@@ -4,7 +4,10 @@
 
 use PHPStan\Type\Type;
 
-/** @api */
+/**
+ * @api
+ * @api-do-not-implement
+ */
 interface TypedTag
 {
 
diff --git a/src/Reflection/Callables/CallableParametersAcceptor.php b/src/Reflection/Callables/CallableParametersAcceptor.php
@@ -24,6 +24,7 @@
  * - Expressions that are invalidated by calling this callable
  *
  * @api
+ * @api-do-not-implement
  */
 interface CallableParametersAcceptor extends ParametersAcceptor
 {
diff --git a/src/Reflection/ClassConstantReflection.php b/src/Reflection/ClassConstantReflection.php
@@ -19,6 +19,7 @@
  * This is the return type of Type::getConstant() and Scope::getConstantReflection().
  *
  * @api
+ * @api-do-not-implement
  */
 interface ClassConstantReflection extends ClassMemberReflection, ConstantReflection
 {
diff --git a/src/Reflection/ClassMemberAccessAnswerer.php b/src/Reflection/ClassMemberAccessAnswerer.php
@@ -15,6 +15,7 @@
  * OutOfClassScope, is used when accessing members from outside any class.
  *
  * @api
+ * @api-do-not-implement
  */
 interface ClassMemberAccessAnswerer
 {
diff --git a/src/Reflection/ClassMemberReflection.php b/src/Reflection/ClassMemberReflection.php
@@ -13,6 +13,7 @@
  * work with the more specific child interfaces.
  *
  * @api
+ * @api-do-not-implement
  */
 interface ClassMemberReflection
 {
diff --git a/src/Reflection/ConstantReflection.php b/src/Reflection/ConstantReflection.php
@@ -13,6 +13,7 @@
  * with class-specific features (declaring class, value expression, native type).
  *
  * @api
+ * @api-do-not-implement
  */
 interface ConstantReflection
 {
diff --git a/src/Reflection/ExtendedMethodReflection.php b/src/Reflection/ExtendedMethodReflection.php
@@ -26,6 +26,7 @@
  * This is the return type of Type::getMethod() and Scope::getMethodReflection().
  *
  * @api
+ * @api-do-not-implement
  */
 interface ExtendedMethodReflection extends MethodReflection
 {
diff --git a/src/Reflection/ExtendedParameterReflection.php b/src/Reflection/ExtendedParameterReflection.php
@@ -5,7 +5,10 @@
 use PHPStan\TrinaryLogic;
 use PHPStan\Type\Type;
 
-/** @api */
+/**
+ * @api
+ * @api-do-not-implement
+ */
 interface ExtendedParameterReflection extends ParameterReflection
 {
 
diff --git a/src/Reflection/ExtendedParametersAcceptor.php b/src/Reflection/ExtendedParametersAcceptor.php
@@ -17,6 +17,7 @@
  * ExtendedMethodReflection::getVariants().
  *
  * @api
+ * @api-do-not-implement
  */
 interface ExtendedParametersAcceptor extends ParametersAcceptor
 {
diff --git a/src/Reflection/ExtendedPropertyReflection.php b/src/Reflection/ExtendedPropertyReflection.php
@@ -24,6 +24,7 @@
  * and Type::getStaticProperty().
  *
  * @api
+ * @api-do-not-implement
  */
 interface ExtendedPropertyReflection extends PropertyReflection
 {
diff --git a/src/Reflection/FunctionReflection.php b/src/Reflection/FunctionReflection.php
@@ -19,6 +19,7 @@
  * FunctionReflection or MethodReflection.
  *
  * @api
+ * @api-do-not-implement
  */
 interface FunctionReflection
 {
diff --git a/src/Reflection/NamespaceAnswerer.php b/src/Reflection/NamespaceAnswerer.php
@@ -9,6 +9,7 @@
  * against the current namespace and use statements.
  *
  * @api
+ * @api-do-not-implement
  */
 interface NamespaceAnswerer
 {
diff --git a/src/Reflection/ReflectionProvider.php b/src/Reflection/ReflectionProvider.php
@@ -5,7 +5,10 @@
 use PhpParser\Node;
 use PHPStan\Analyser\Scope;
 
-/** @api */
+/**
+ * @api
+ * @api-do-not-implement
+ */
 interface ReflectionProvider
 {
 
diff --git a/src/Rules/Api/ApiClassImplementsRule.php b/src/Rules/Api/ApiClassImplementsRule.php
@@ -12,7 +12,6 @@
 use PHPStan\Rules\RuleErrorBuilder;
 use function array_merge;
 use function count;
-use function in_array;
 use function sprintf;
 
 /**
@@ -67,18 +66,19 @@ private function checkName(Scope $scope, Node\Name $name): array
 			'https://github.com/phpstan/phpstan/discussions',
 		))->build();
 
-		if (in_array($implementedClassReflection->getName(), BcUncoveredInterface::CLASSES, true)) {
-			return [$ruleError];
-		}
-
 		$docBlock = $implementedClassReflection->getResolvedPhpDoc();
 		if ($docBlock === null) {
 			return [$ruleError];
 		}
 
 		foreach ($docBlock->getPhpDocNodes() as $phpDocNode) {
-			$apiTags = $phpDocNode->getTagsByName('@api');
-			if (count($apiTags) > 0) {
+			if (count($phpDocNode->getTagsByName('@api-do-not-implement')) > 0) {
+				return [$ruleError];
+			}
+		}
+
+		foreach ($docBlock->getPhpDocNodes() as $phpDocNode) {
+			if (count($phpDocNode->getTagsByName('@api')) > 0) {
 				return [];
 			}
 		}
diff --git a/src/Rules/Api/ApiInterfaceExtendsRule.php b/src/Rules/Api/ApiInterfaceExtendsRule.php
@@ -12,7 +12,6 @@
 use PHPStan\Rules\RuleErrorBuilder;
 use function array_merge;
 use function count;
-use function in_array;
 use function sprintf;
 
 /**
@@ -67,18 +66,19 @@ private function checkName(Scope $scope, Node\Name $name): array
 			'https://github.com/phpstan/phpstan/discussions',
 		))->build();
 
-		if (in_array($extendedInterfaceReflection->getName(), BcUncoveredInterface::CLASSES, true)) {
-			return [$ruleError];
-		}
-
 		$docBlock = $extendedInterfaceReflection->getResolvedPhpDoc();
 		if ($docBlock === null) {
 			return [$ruleError];
 		}
 
 		foreach ($docBlock->getPhpDocNodes() as $phpDocNode) {
-			$apiTags = $phpDocNode->getTagsByName('@api');
-			if (count($apiTags) > 0) {
+			if (count($phpDocNode->getTagsByName('@api-do-not-implement')) > 0) {
+				return [$ruleError];
+			}
+		}
+
+		foreach ($docBlock->getPhpDocNodes() as $phpDocNode) {
+			if (count($phpDocNode->getTagsByName('@api')) > 0) {
 				return [];
 			}
 		}
diff --git a/src/Rules/Api/BcUncoveredInterface.php b/src/Rules/Api/BcUncoveredInterface.php
diff --git a/src/Rules/FileRuleError.php b/src/Rules/FileRuleError.php
@@ -2,7 +2,10 @@
 
 namespace PHPStan\Rules;
 
-/** @api */
+/**
+ * @api
+ * @api-do-not-implement
+ */
 interface FileRuleError extends RuleError
 {
 
diff --git a/src/Rules/IdentifierRuleError.php b/src/Rules/IdentifierRuleError.php
@@ -2,7 +2,10 @@
 
 namespace PHPStan\Rules;
 
-/** @api */
+/**
+ * @api
+ * @api-do-not-implement
+ */
 interface IdentifierRuleError extends RuleError
 {
 
diff --git a/src/Rules/LineRuleError.php b/src/Rules/LineRuleError.php
@@ -2,7 +2,10 @@
 
 namespace PHPStan\Rules;
 
-/** @api */
+/**
+ * @api
+ * @api-do-not-implement
+ */
 interface LineRuleError extends RuleError
 {
 
diff --git a/src/Rules/MetadataRuleError.php b/src/Rules/MetadataRuleError.php
@@ -2,7 +2,10 @@
 
 namespace PHPStan\Rules;
 
-/** @api */
+/**
+ * @api
+ * @api-do-not-implement
+ */
 interface MetadataRuleError extends RuleError
 {
 
diff --git a/src/Rules/NonIgnorableRuleError.php b/src/Rules/NonIgnorableRuleError.php
@@ -2,7 +2,10 @@
 
 namespace PHPStan\Rules;
 
-/** @api */
+/**
+ * @api
+ * @api-do-not-implement
+ */
 interface NonIgnorableRuleError extends RuleError
 {
 
diff --git a/src/Rules/RuleError.php b/src/Rules/RuleError.php
@@ -2,7 +2,10 @@
 
 namespace PHPStan\Rules;
 
-/** @api */
+/**
+ * @api
+ * @api-do-not-implement
+ */
 interface RuleError
 {
 
diff --git a/src/Rules/TipRuleError.php b/src/Rules/TipRuleError.php
diff --git a/src/Type/CompoundType.php b/src/Type/CompoundType.php
diff --git a/src/Type/Generic/TemplateType.php b/src/Type/Generic/TemplateType.php
diff --git a/src/Type/Type.php b/src/Type/Type.php
diff --git a/src/Type/TypeWithClassName.php b/src/Type/TypeWithClassName.php

Original file line number	Diff line number	Diff line change
`@@ -42,6 +42,7 @@`
`42`	`42`	`* $x is of type Foo.`
`43`	`43`	`*`
`44`	`44`	`* @api`
	`45`	`+ * @api-do-not-implement`
`45`	`46`	`*/`
`46`	`47`	`interface Scope extends ClassMemberAccessAnswerer, NamespaceAnswerer`
`47`	`48`	`{`
Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,10 @@`
`2`	`2`
`3`	`3`	`namespace PHPStan\Command;`
`4`	`4`
`5`		`-/** @api */`
	`5`	`+/**`
	`6`	`+ * @api`
	`7`	`+ * @api-do-not-implement`
	`8`	`+ */`
`6`	`9`	`interface Output`
`7`	`10`	`{`
`8`	`11`
Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,10 @@`
`2`	`2`
`3`	`3`	`namespace PHPStan\DependencyInjection;`
`4`	`4`
`5`		`-/** @api */`
	`5`	`+/**`
	`6`	`+ * @api`
	`7`	`+ * @api-do-not-implement`
	`8`	`+ */`
`6`	`9`	`interface Container`
`7`	`10`	`{`
`8`	`11`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,10 @@`
`4`	`4`
`5`	`5`	`use PhpParser\Node;`
`6`	`6`
`7`		`-/** @api */`
	`7`	`+/**`
	`8`	`+ * @api`
	`9`	`+ * @api-do-not-implement`
	`10`	`+ */`
`8`	`11`	`interface VirtualNode extends Node`
`9`	`12`	`{`
`10`	`13`
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,10 @@`
`4`	`4`
`5`	`5`	`use PHPStan\Type\Type;`
`6`	`6`
`7`		`-/** @api */`
	`7`	`+/**`
	`8`	`+ * @api`
	`9`	`+ * @api-do-not-implement`
	`10`	`+ */`
`8`	`11`	`interface TypedTag`
`9`	`12`	`{`
`10`	`13`
Original file line number	Diff line number	Diff line change
`@@ -24,6 +24,7 @@`
`24`	`24`	`* - Expressions that are invalidated by calling this callable`
`25`	`25`	`*`
`26`	`26`	`* @api`
	`27`	`+ * @api-do-not-implement`
`27`	`28`	`*/`
`28`	`29`	`interface CallableParametersAcceptor extends ParametersAcceptor`
`29`	`30`	`{`
Original file line number	Diff line number	Diff line change
`@@ -19,6 +19,7 @@`
`19`	`19`	`* This is the return type of Type::getConstant() and Scope::getConstantReflection().`
`20`	`20`	`*`
`21`	`21`	`* @api`
	`22`	`+ * @api-do-not-implement`
`22`	`23`	`*/`
`23`	`24`	`interface ClassConstantReflection extends ClassMemberReflection, ConstantReflection`
`24`	`25`	`{`
Original file line number	Diff line number	Diff line change
`@@ -15,6 +15,7 @@`
`15`	`15`	`* OutOfClassScope, is used when accessing members from outside any class.`
`16`	`16`	`*`
`17`	`17`	`* @api`
	`18`	`+ * @api-do-not-implement`
`18`	`19`	`*/`
`19`	`20`	`interface ClassMemberAccessAnswerer`
`20`	`21`	`{`