diff --git a/composer.json b/composer.json index 0e255c4d0f8e0ce36a83c55ae466290f402eeffa..1f500e6744ca7373feec7075e93012934e640088 100644 --- a/composer.json +++ b/composer.json @@ -41,7 +41,7 @@ }, "suggest": { "tracy/tracy": "For more detailed error messages.", - "nikic/php-parser": "To able to use KeepMethodDecorator." + "nikic/php-parser": "To be able to use Preserve attribute." }, "bin": [ "bin/scaffolder" diff --git a/readme.md b/readme.md index d86179be11fa2dd86ed7e0ece76d12336cb8b816..6a6af097800470e372fdeeb617da4adab7f28094 100644 --- a/readme.md +++ b/readme.md @@ -4,7 +4,7 @@ It was designed to generated classes with none to simple logic. Typical usage is - data transfer objects (DTOs), - events in event-sourced model, -- simple value objects (simple logic can be embedded using `#[KeepMethod]` attribute – see below). +- simple value objects (simple logic can be embedded using `#[Preserve]` attribute – see below). It is developed at [gitlab.grifart.cz](https://gitlab.grifart.cz/grifart/scaffolder), automatically mirrored to [GitHub](https://github.com/grifart/scaffolder) and distributed over Composer [packagist:grifart/scaffolder](https://packagist.org/packages/grifart/scaffolder). @@ -561,10 +561,10 @@ final class Name } ``` -We want to add a `getFullName()` method and preserve it when scaffolder runs next time. The trick is to mark the method with the `#[KeepMethod]` attribute: +We want to add a `getFullName()` method and preserve it when scaffolder runs next time. The trick is to mark the method with the `#[Preserve]` attribute: ```php -#[\Grifart\ClassScaffolder\KeepMethod] +#[\Grifart\ClassScaffolder\Preserve] public function getFullName(): string { return $this->firstName . ' ' . $this->lastName; @@ -577,7 +577,7 @@ and add the `preservedAnnotatedMethods()` capability to the definition: $definition->with(Capabilities\preservedAnnotatedMethods()) ``` -The next time you run scaffolder, the `getFullName()` method will be kept intact as long as it has the `#[KeepMethod]` attribute. +The next time you run scaffolder, the `getFullName()` method will be kept intact as long as it has the `#[Preserve]` attribute. Alternatively, you can use the `preservedMethod($methodName)` capability that keeps only methods that are explicitly listed in the capability function. diff --git a/src/Capabilities/PreservedAnnotatedMethods.php b/src/Capabilities/PreservedAnnotatedMethods.php index 8a135a5fe9a53ccff490b7ca089af13527a0ca48..038d73a51417b4ea4c10f107fd1eb2bf6aee81b8 100644 --- a/src/Capabilities/PreservedAnnotatedMethods.php +++ b/src/Capabilities/PreservedAnnotatedMethods.php @@ -7,6 +7,7 @@ namespace Grifart\ClassScaffolder\Capabilities; use Grifart\ClassScaffolder\ClassInNamespace; use Grifart\ClassScaffolder\Definition\ClassDefinition; use Grifart\ClassScaffolder\KeepMethod; +use Grifart\ClassScaffolder\Preserve; use Nette\PhpGenerator\Method; /** @@ -27,17 +28,27 @@ final class PreservedAnnotatedMethods implements Capability foreach ($current->getClassType()->getMethods() as $existingMethod) { foreach ($existingMethod->getAttributes() as $attribute) { - if ($attribute->getName() === KeepMethod::class) { + if ($attribute->getName() === Preserve::class) { self::transferMethod($draft, $existingMethod); break; // continue to next method } + + if ($attribute->getName() === KeepMethod::class) { + self::transferMethod($draft, $existingMethod, KeepMethod::class); + break; // continue to next method + } } } } - private static function transferMethod(ClassInNamespace $draft, Method $methodToBeTransferred): void + /** + * @param string|null $nonStandardPreservedUseStatement temporary, can be removed with end of support for KeepMethod + */ + private static function transferMethod(ClassInNamespace $draft, Method $methodToBeTransferred, string $nonStandardPreservedUseStatement = null): void { - $draft->getNamespace()->addUse(KeepMethod::class); + $draft->getNamespace()->addUse($nonStandardPreservedUseStatement !== null ? + $nonStandardPreservedUseStatement : + Preserve::class); $targetClass = $draft->getClassType(); $targetClass->setMethods([ diff --git a/src/Capabilities/PreservedMethod.php b/src/Capabilities/PreservedMethod.php index 7ed45d8b9c9db7baf30ca54f6bc3f1cd4a77e527..7ba74ae5d7eeac851286d03235fcb99f8de5058b 100644 --- a/src/Capabilities/PreservedMethod.php +++ b/src/Capabilities/PreservedMethod.php @@ -25,11 +25,11 @@ final class PreservedMethod implements Capability // method already exists, just transfer it to new class if ($current !== null && $current->getClassType()->hasMethod($this->methodName)) { - $keptMethod = $current->getClassType()->getMethod($this->methodName); + $preservedMethod = $current->getClassType()->getMethod($this->methodName); $classToBeGenerated->setMethods([ ...\array_values($classToBeGenerated->getMethods()), - $keptMethod, + $preservedMethod, ]); return; } @@ -42,12 +42,12 @@ final class PreservedMethod implements Capability return $method; }; - $methodToBeKept = $classToBeGenerated->hasMethod($this->methodName) + $preservedMethod = $classToBeGenerated->hasMethod($this->methodName) ? $classToBeGenerated->getMethod($this->methodName) : $addMethodStub($classToBeGenerated); - $methodToBeKept->setComment( - 'This method is kept while scaffolding.' . "\n" . - $methodToBeKept->getComment() + $preservedMethod->setComment( + 'This method is preserved while scaffolding.' . "\n" . + $preservedMethod->getComment() ); } } diff --git a/src/KeepMethod.php b/src/KeepMethod.php index 73bdd738fa7fd42b5b2fd4ac68e59d51799cb7f7..5497e332f5d2bc8b9c181b1b32a30bdc3e4f91ef 100644 --- a/src/KeepMethod.php +++ b/src/KeepMethod.php @@ -5,6 +5,9 @@ namespace Grifart\ClassScaffolder; use Attribute; +/** + * @deprecated use Grifart\ClassScaffolder\Preserve instead + */ #[Attribute(Attribute::TARGET_METHOD)] final class KeepMethod {} diff --git a/src/Preserve.php b/src/Preserve.php new file mode 100644 index 0000000000000000000000000000000000000000..bfc9b4c44f13df43c5a9e843e9d75cf085d1ade5 --- /dev/null +++ b/src/Preserve.php @@ -0,0 +1,10 @@ +<?php declare(strict_types = 1); + +namespace Grifart\ClassScaffolder; + +use Attribute; + + +#[Attribute(Attribute::TARGET_METHOD)] +final class Preserve +{} diff --git a/tests/Capabilities/PreservedAnnotatedMethods/ExistentClass.php b/tests/Capabilities/PreservedAnnotatedMethods/ExistentClass.php index 71a5b4b3a4b70eb84d329f347ae33d40c7e33fe8..b3a17f43fd279a2f0cad6055f2ff24edc0af7168 100644 --- a/tests/Capabilities/PreservedAnnotatedMethods/ExistentClass.php +++ b/tests/Capabilities/PreservedAnnotatedMethods/ExistentClass.php @@ -6,25 +6,25 @@ namespace Grifart\ClassScaffolder\Test\Capabilities\PreservedAnnotatedMethods; use Grifart\ClassScaffolder\Definition\ClassDefinition; use Grifart\ClassScaffolder\Definition\ClassDefinitionBuilder; -use Grifart\ClassScaffolder\KeepMethod; +use Grifart\ClassScaffolder\Preserve; final class ExistentClass { - #[KeepMethod] - public function methodToBeKept(): mixed + #[Preserve] + public function preservedMethod(): mixed { return 'whatever'; } - #[KeepMethod] - public function methodToBeKeptWithParam(int $whatever): void {} + #[Preserve] + public function preservedMethodWithParam(int $whatever): void {} /** @param iterable<int, string[]> $whatever */ - #[KeepMethod] - public function methodToBeKeptWithPhpDocParam(iterable $whatever): void {} + #[Preserve] + public function preservedMethodWithPhpDocParam(iterable $whatever): void {} - #[KeepMethod] - public function methodToBeKeptWithImportedUses(ClassDefinitionBuilder $builder): string { + #[Preserve] + public function preservedMethodWithImportedUses(ClassDefinitionBuilder $builder): string { return ClassDefinition::class; } @@ -33,8 +33,8 @@ final class ExistentClass * @return void * @throws \Throwable */ - #[KeepMethod] - public function methodToBeKeptWithAnnotation(): void { + #[Preserve] + public function preservedMethodWithAnnotation(): void { } public function methodToBeRemoved(): void diff --git a/tests/Capabilities/PreservedAnnotatedMethods/PreservedAnnotatedMethodsTest.expected.phps b/tests/Capabilities/PreservedAnnotatedMethods/PreservedAnnotatedMethodsTest.expected.phps index 9396bebbf2a4d53d849aad578c3c3a6bfe95bf42..907c82578344c7b41a147d972e5eed12e8a4ed2e 100644 --- a/tests/Capabilities/PreservedAnnotatedMethods/PreservedAnnotatedMethodsTest.expected.phps +++ b/tests/Capabilities/PreservedAnnotatedMethods/PreservedAnnotatedMethodsTest.expected.phps @@ -10,19 +10,19 @@ namespace Grifart\ClassScaffolder\Test\Capabilities\PreservedAnnotatedMethods; use Grifart\ClassScaffolder\Definition\ClassDefinition; use Grifart\ClassScaffolder\Definition\ClassDefinitionBuilder; -use Grifart\ClassScaffolder\KeepMethod; +use Grifart\ClassScaffolder\Preserve; final class ExistentClass { - #[KeepMethod] - public function methodToBeKept(): mixed + #[Preserve] + public function preservedMethod(): mixed { return 'whatever'; } - #[KeepMethod] - public function methodToBeKeptWithParam(int $whatever): void + #[Preserve] + public function preservedMethodWithParam(int $whatever): void { } @@ -30,14 +30,14 @@ final class ExistentClass /** * @param iterable<int, string[]> $whatever */ - #[KeepMethod] - public function methodToBeKeptWithPhpDocParam(iterable $whatever): void + #[Preserve] + public function preservedMethodWithPhpDocParam(iterable $whatever): void { } - #[KeepMethod] - public function methodToBeKeptWithImportedUses(ClassDefinitionBuilder $builder): string + #[Preserve] + public function preservedMethodWithImportedUses(ClassDefinitionBuilder $builder): string { return ClassDefinition::class; } @@ -48,8 +48,8 @@ final class ExistentClass * @return void * @throws \Throwable */ - #[KeepMethod] - public function methodToBeKeptWithAnnotation(): void + #[Preserve] + public function preservedMethodWithAnnotation(): void { } } diff --git a/tests/Capabilities/PreservedMethod/ExistentClass.php b/tests/Capabilities/PreservedMethod/ExistentClass.php index 1f623d5d14a424b43166cc3115ca09a382e83013..95f2f30cd4c31a05770faa349231fff38e45fe58 100644 --- a/tests/Capabilities/PreservedMethod/ExistentClass.php +++ b/tests/Capabilities/PreservedMethod/ExistentClass.php @@ -9,17 +9,17 @@ use Grifart\ClassScaffolder\Definition\ClassDefinitionBuilder; final class ExistentClass { - public function methodToBeKept(): mixed + public function preservedMethod(): mixed { return 'whatever'; } - public function methodToBeKeptWithParam(int $whatever): void {} + public function preservedMethodWithParam(int $whatever): void {} /** @param iterable<int, string[]> $whatever */ - public function methodToBeKeptWithPhpDocParam(iterable $whatever): void {} + public function preservedMethodWithPhpDocParam(iterable $whatever): void {} - public function methodToBeKeptWithImportedUses(ClassDefinitionBuilder $builder): string { + public function preservedMethodWithImportedUses(ClassDefinitionBuilder $builder): string { return ClassDefinition::class; } @@ -28,7 +28,7 @@ final class ExistentClass * @return void * @throws \Throwable */ - public function methodToBeKeptWithAnnotation(): void { + public function preservedMethodWithAnnotation(): void { } public function methodToBeRemoved(): void diff --git a/tests/Capabilities/PreservedMethod/PreservedMethodTest.expected.phps b/tests/Capabilities/PreservedMethod/PreservedMethodTest.expected.phps index 3c39ef4790097778e0316141e447b7a88f6ecc86..40bd0b84f592760cded3c416729d41c758eafc2f 100644 --- a/tests/Capabilities/PreservedMethod/PreservedMethodTest.expected.phps +++ b/tests/Capabilities/PreservedMethod/PreservedMethodTest.expected.phps @@ -14,7 +14,7 @@ use Grifart\ClassScaffolder\Definition\ClassDefinitionBuilder; final class ExistentClass { /** - * This method is kept while scaffolding. + * This method is preserved while scaffolding. */ public function newMethod(): void { @@ -22,13 +22,13 @@ final class ExistentClass } - public function methodToBeKept(): mixed + public function preservedMethod(): mixed { return 'whatever'; } - public function methodToBeKeptWithParam(int $whatever): void + public function preservedMethodWithParam(int $whatever): void { } @@ -36,12 +36,12 @@ final class ExistentClass /** * @param iterable<int, string[]> $whatever */ - public function methodToBeKeptWithPhpDocParam(iterable $whatever): void + public function preservedMethodWithPhpDocParam(iterable $whatever): void { } - public function methodToBeKeptWithImportedUses(ClassDefinitionBuilder $builder): string + public function preservedMethodWithImportedUses(ClassDefinitionBuilder $builder): string { return ClassDefinition::class; } @@ -52,7 +52,7 @@ final class ExistentClass * @return void * @throws \Throwable */ - public function methodToBeKeptWithAnnotation(): void + public function preservedMethodWithAnnotation(): void { } } diff --git a/tests/Capabilities/PreservedMethod/PreservedMethodTest.phpt b/tests/Capabilities/PreservedMethod/PreservedMethodTest.phpt index e437e2955b3b712ecafd94df63808bbc2ba3d115..106099be010aa911cd8495385ff23c77ddb0c141 100644 --- a/tests/Capabilities/PreservedMethod/PreservedMethodTest.phpt +++ b/tests/Capabilities/PreservedMethod/PreservedMethodTest.phpt @@ -19,11 +19,11 @@ final class PreservedMethodTest extends CapabilityTestCase return [ preservedUseStatements(), preservedMethod('newMethod'), - preservedMethod('methodToBeKept'), - preservedMethod('methodToBeKeptWithParam'), - preservedMethod('methodToBeKeptWithPhpDocParam'), - preservedMethod('methodToBeKeptWithImportedUses'), - preservedMethod('methodToBeKeptWithAnnotation'), + preservedMethod('preservedMethod'), + preservedMethod('preservedMethodWithParam'), + preservedMethod('preservedMethodWithPhpDocParam'), + preservedMethod('preservedMethodWithImportedUses'), + preservedMethod('preservedMethodWithAnnotation'), ]; }