Merge branch 'deprecated-capability' into 'master'

deprecated()

See merge request !60

src/Capabilities/Deprecated.php

+<?php declare(strict_types = 1);
+
+namespace Grifart\ClassScaffolder\Capabilities;
+
+use Grifart\ClassScaffolder\ClassInNamespace;
+use Grifart\ClassScaffolder\Definition\ClassDefinition;
+use function sprintf;
+
+
+final class Deprecated implements Capability
+{
+
+	/**
+	 * @param class-string $replacement
+	 */
+	public function __construct(
+		private ?string $description = null,
+		private ?string $replacement = null,
+	) {}
+
+
+	public function applyTo(
+		ClassDefinition $definition,
+		ClassInNamespace $draft,
+		?ClassInNamespace $current,
+	): void
+	{
+		$annotation = '@deprecated';
+		if ($this->description !== null) {
+			$annotation .= ' ' . $this->description;
+		}
+
+		if ($this->replacement !== null) {
+			$annotation .= $this->description !== null ? ', ' : ' ';
+			$annotation .= sprintf('use {@see %s} instead', $this->replacement);
+		}
+
+		$draft->getClassType()->addComment($annotation);
+	}
+
+}

src/Capabilities/functions.php

@@ -8,6 +8,16 @@ function constructorWithPromotedProperties(): ConstructorWithPromotedProperties
 	return new ConstructorWithPromotedProperties();
 }
 
+/**
+ * @param class-string $replacement
+ */
+function deprecated(
+	?string $description = null,
+	?string $replacement = null,
+): Deprecated {
+	return new Deprecated($description, $replacement);
+}
+
 function getters(): Getters {
 	return new Getters();
 }

tests/Capabilities/Deprecated/DeprecatedTest.expected.onlyAnnotation.phps

+<?php
+
+/**
+ * Do not edit. This is generated file. Modify definition file instead.
+ */
+
+declare(strict_types=1);
+
+/**
+ * @deprecated
+ */
+final class ClassName
+{
+}

tests/Capabilities/Deprecated/DeprecatedTest.expected.withAll.phps

+<?php
+
+/**
+ * Do not edit. This is generated file. Modify definition file instead.
+ */
+
+declare(strict_types=1);
+
+/**
+ * @deprecated will be removed in v4.0.0, use {@see Grifart\ClassScaffolder\Test\Capabilities\Deprecated\Replacement} instead
+ */
+final class ClassName
+{
+}

tests/Capabilities/Deprecated/DeprecatedTest.expected.withDescription.phps

+<?php
+
+/**
+ * Do not edit. This is generated file. Modify definition file instead.
+ */
+
+declare(strict_types=1);
+
+/**
+ * @deprecated will be removed in v4.0.0
+ */
+final class ClassName
+{
+}

tests/Capabilities/Deprecated/DeprecatedTest.expected.withReplacement.phps

+<?php
+
+/**
+ * Do not edit. This is generated file. Modify definition file instead.
+ */
+
+declare(strict_types=1);
+
+/**
+ * @deprecated use {@see Grifart\ClassScaffolder\Test\Capabilities\Deprecated\Replacement} instead
+ */
+final class ClassName
+{
+}

tests/Capabilities/Deprecated/DeprecatedTest.phpt

+<?php declare(strict_types = 1);
+
+namespace Grifart\ClassScaffolder\Test\Capabilities\Deprecated;
+
+use Grifart\ClassScaffolder\ClassGenerator;
+use Grifart\ClassScaffolder\Definition\ClassDefinition;
+use Tester\Assert;
+use Tester\TestCase;
+use function Grifart\ClassScaffolder\Capabilities\deprecated;
+use function Grifart\ClassScaffolder\Definition\definitionOf;
+
+
+require __DIR__ . '/../../bootstrap.php';
+
+final class DeprecatedTest extends TestCase
+{
+	private function doAssert(
+		ClassDefinition $definition,
+		string $expectedFilePath,
+	): void
+	{
+		$generator = new ClassGenerator();
+		$phpFile = $generator->generateClass($definition);
+		$code = (string) $phpFile;
+
+		Assert::matchFile($expectedFilePath, $code);
+	}
+
+	public function testWithoutParams(): void
+	{
+		$this->doAssert(
+			definition: definitionOf('ClassName')
+				->with(deprecated()),
+			expectedFilePath: __DIR__ . '/DeprecatedTest.expected.onlyAnnotation.phps',
+		);
+	}
+
+	public function testWithDescription(): void
+	{
+		$this->doAssert(
+			definition: definitionOf('ClassName')
+				->with(deprecated(description: 'will be removed in v4.0.0')),
+			expectedFilePath: __DIR__ . '/DeprecatedTest.expected.withDescription.phps',
+		);
+	}
+
+	public function testWithReplacement(): void
+	{
+		$this->doAssert(
+			definition: definitionOf('ClassName')
+				->with(deprecated(replacement: Replacement::class)),
+			expectedFilePath: __DIR__ . '/DeprecatedTest.expected.withReplacement.phps',
+		);
+	}
+
+	public function testWithAll(): void
+	{
+		$this->doAssert(
+			definition: definitionOf('ClassName')
+				->with(deprecated(
+					description: 'will be removed in v4.0.0',
+					replacement: Replacement::class,
+				)),
+			expectedFilePath: __DIR__ . '/DeprecatedTest.expected.withAll.phps',
+		);
+	}
+}
+
+(new DeprecatedTest())->run();

tests/Capabilities/Deprecated/Replacement.php

+<?php declare(strict_types = 1);
+
+namespace Grifart\ClassScaffolder\Test\Capabilities\Deprecated;
+
+
+final class Replacement
+{}