Add unused-label rule on level 4, gated behind bleeding edge

The new UnusedLabelRule reports when a label is never targeted
by any goto in the same scope. It uses the LABEL_IS_USED attribute
set by GotoLabelVisitor.

Enabled only with bleeding edge via the unusedLabel feature toggle.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ondrejmirtes

Makefile

@@ -44,6 +44,7 @@ lint:
 		--exclude tests/PHPStan/Rules/Keywords/data/continue-break-property-hook.php \
 		--exclude tests/PHPStan/Rules/Keywords/data/goto-undefined-label.php \
 		--exclude tests/PHPStan/Rules/Keywords/data/goto-undefined-label-property-hook.php \
+		--exclude tests/PHPStan/Rules/Keywords/data/unused-label-property-hook.php \
 		--exclude tests/PHPStan/Rules/Keywords/data/bug-13790-break.php \
 		--exclude tests/PHPStan/Rules/Keywords/data/bug-13790-continue.php \
 		--exclude tests/PHPStan/Rules/Properties/data/invalid-callable-property-type.php \

conf/bleedingEdge.neon

@@ -19,3 +19,4 @@ parameters:
 		checkDateIntervalConstructor: true
 		reportMethodPurityOverride: true
 		checkDynamicConstantNameValues: true
+		unusedLabel: true

conf/config.level4.neon

@@ -12,6 +12,8 @@ conditionalTags:
 		phpstan.rules.rule: %exceptions.check.tooWideThrowType%
 	PHPStan\Rules\Exceptions\TooWidePropertyHookThrowTypeRule:
 		phpstan.rules.rule: %exceptions.check.tooWideThrowType%
+	PHPStan\Rules\Keywords\UnusedLabelRule:
+		phpstan.rules.rule: %featureToggles.unusedLabel%
 
 parameters:
 	checkAdvancedIsset: true
@@ -30,3 +32,6 @@ services:
 		class: PHPStan\Rules\Exceptions\TooWidePropertyHookThrowTypeRule
 		arguments:
 			checkProtectedAndPublicMethods: %checkTooWideThrowTypesInProtectedAndPublicMethods%
+
+	-
+		class: PHPStan\Rules\Keywords\UnusedLabelRule

conf/config.neon

@@ -46,6 +46,7 @@ parameters:
 		checkDateIntervalConstructor: false
 		reportMethodPurityOverride: false
 		checkDynamicConstantNameValues: false
+		unusedLabel: false
 	fileExtensions:
 		- php
 	checkAdvancedIsset: false

conf/parametersSchema.neon

@@ -48,6 +48,7 @@ parametersSchema:
 		checkDateIntervalConstructor: bool()
 		reportMethodPurityOverride: bool()
 		checkDynamicConstantNameValues: bool()
+		unusedLabel: bool()
 	])
 	fileExtensions: listOf(string())
 	checkAdvancedIsset: bool()

src/Parser/GotoLabelVisitor.php

@@ -23,6 +23,8 @@ final class GotoLabelVisitor extends NodeVisitorAbstract
 
 	public const GOTO_LABEL_UNDEFINED_ATTRIBUTE = 'gotoLabelUndefined';
 
+	public const LABEL_IS_USED_ATTRIBUTE = 'labelIsUsed';
+
 	/** @var array<int, array{labels: array<string, Node\Stmt\Label>, gotos: list<Goto_>}> */
 	private array $scopeStack = [];
 
@@ -261,12 +263,18 @@ private function popScope(): void
 			return;
 		}
 
+		$usedLabelNames = [];
 		foreach ($frame['gotos'] as $goto) {
-			if (isset($frame['labels'][$goto->name->toString()])) {
-				continue;
+			$gotoName = $goto->name->toString();
+			if (!isset($frame['labels'][$gotoName])) {
+				$goto->setAttribute(self::GOTO_LABEL_UNDEFINED_ATTRIBUTE, true);
+			} else {
+				$usedLabelNames[$gotoName] = true;
 			}
+		}
 
-			$goto->setAttribute(self::GOTO_LABEL_UNDEFINED_ATTRIBUTE, true);
+		foreach ($frame['labels'] as $name => $label) {
+			$label->setAttribute(self::LABEL_IS_USED_ATTRIBUTE, isset($usedLabelNames[$name]));
 		}
 	}
 

src/Rules/Keywords/UnusedLabelRule.php

@@ -0,0 +1,39 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Keywords;
+
+use PhpParser\Node;
+use PHPStan\Analyser\Scope;
+use PHPStan\Parser\GotoLabelVisitor;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use function sprintf;
+
+/**
+ * @implements Rule<Node\Stmt\Label>
+ */
+final class UnusedLabelRule implements Rule
+{
+
+	public function getNodeType(): string
+	{
+		return Node\Stmt\Label::class;
+	}
+
+	public function processNode(Node $node, Scope $scope): array
+	{
+		if ($node->getAttribute(GotoLabelVisitor::LABEL_IS_USED_ATTRIBUTE) !== false) {
+			return [];
+		}
+
+		return [
+			RuleErrorBuilder::message(sprintf(
+				"Label '%s' is unused.",
+				$node->name->toString(),
+			))
+				->identifier('label.unused')
+				->build(),
+		];
+	}
+
+}

tests/PHPStan/Rules/Keywords/UnusedLabelRuleTest.php

@@ -0,0 +1,53 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\Keywords;
+
+use PHPStan\Rules\Rule;
+use PHPStan\Testing\RuleTestCase;
+use PHPUnit\Framework\Attributes\RequiresPhp;
+
+/**
+ * @extends RuleTestCase<UnusedLabelRule>
+ */
+class UnusedLabelRuleTest extends RuleTestCase
+{
+
+	protected function getRule(): Rule
+	{
+		return new UnusedLabelRule();
+	}
+
+	public function testRule(): void
+	{
+		$this->analyse([__DIR__ . '/data/unused-label.php'], [
+			[
+				"Label 'unused' is unused.",
+				15,
+			],
+			[
+				"Label 'unused1' is unused.",
+				31,
+			],
+			[
+				"Label 'unused2' is unused.",
+				35,
+			],
+			[
+				"Label 'outside' is unused.",
+				41,
+			],
+		]);
+	}
+
+	#[RequiresPhp('>= 8.4.0')]
+	public function testPropertyHook(): void
+	{
+		$this->analyse([__DIR__ . '/data/unused-label-property-hook.php'], [
+			[
+				"Label 'unused' is unused.",
+				21,
+			],
+		]);
+	}
+
+}

tests/PHPStan/Rules/Keywords/data/unused-label-property-hook.php

@@ -0,0 +1,26 @@
+<?php // lint >= 8.4
+
+declare(strict_types = 1);
+
+namespace UnusedLabelPropertyHook;
+
+class Foo
+{
+
+	public int $value {
+		get {
+			goto end;
+			echo "unreachable";
+			end:
+			return 42;
+		}
+	}
+
+	public int $broken {
+		get {
+			unused:
+			return 0;
+		}
+	}
+
+}

tests/PHPStan/Rules/Keywords/data/unused-label.php

@@ -0,0 +1,58 @@
+<?php declare(strict_types = 1);
+
+namespace UnusedLabel;
+
+function usedLabel(): void
+{
+	goto end;
+	echo "unreachable";
+	end:
+	echo "done";
+}
+
+function unusedLabel(): void
+{
+	unused:
+	echo "hello";
+}
+
+function backwardGotoUsed(): void
+{
+	retry:
+	$result = rand(0, 1);
+	if ($result === 0) {
+		goto retry;
+	}
+}
+
+function multipleLabels(): void
+{
+	goto used;
+	unused1:
+	echo "not used";
+	used:
+	echo "used";
+	unused2:
+	echo "not used either";
+}
+
+function crossBoundaryNotUsed(): void
+{
+	outside:
+	$fn = function () {
+		goto inside;
+		inside:
+		echo "hello";
+	};
+	echo "done";
+}
+
+function labelInNestedStructure(): void
+{
+	if (rand(0, 1) === 1) {
+		goto end;
+	}
+	echo "hello";
+	end:
+	echo "done";
+}