Add Rector rules for conversion of classes that extend BenSampo\Enum\Enum to native PHP enums

Author: spawnia

.github/workflows/continuous-integration.yml

@@ -32,7 +32,9 @@ jobs:
         with:
           dependency-versions: ${{ matrix.dependency-versions }}
 
-      - run: vendor/bin/phpunit
+      - run: vendor/bin/phpunit --testsuite=Tests
+
+      - run: vendor/bin/phpunit --testsuite=Rector
 
   static-analysis:
     runs-on: ubuntu-latest

.php-cs-fixer.php

@@ -6,7 +6,9 @@
     ->in(__DIR__)
     ->name('*.php')
     ->notPath('vendor')
+    ->notPath('tests/Enums/Annotate') // Generated
     ->notPath('tests/Enums/AnnotateFixtures') // Matches laminas/laminas-code
+    ->notPath('tests/Enums/ToNative') // Generated
     ->notPath('tests/Enums/ToNativeFixtures') // Matches laminas/laminas-code
     ->ignoreDotFiles(false)
     ->ignoreVCS(true);

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## 6.5.0
+
+### Added
+
+- Add Rector rules for conversion of classes that extend `BenSampo\Enum\Enum` to native PHP enums
+
+### Deprecated
+
+- Deprecate command `enum:to-native` in favor of Rector conversion
+
 ## 6.4.1
 
 ### Fixed

CONTRIBUTING.md

@@ -10,7 +10,7 @@ Hey, thank you for contributing. Here are some tips to make it easy for you.
 1. Think about how the changes you are about to make can be tested, write tests before coding 
 1. Run tests, make sure they fail
 1. Write the actual code to make the tests pass
-1. Run checks with `composer all`
+1. Run checks with `make`
 1. Open a pull request detailing your changes. Make sure to follow the [template](.github/PULL_REQUEST_TEMPLATE.md)
 
 ## Testing
@@ -28,7 +28,7 @@ failing test.
 Run the testsuite:
 
 ```sh
-composer test
+make test
 ```
 
 ## Codestyle
@@ -37,17 +37,16 @@ Formatting is automated through [php-cs-fixer](https://github.com/friendsofphp/p
 
 Apply automated fixes:
 
-```bash
-composer fix
+```sh
+make fix
 ```
 
-
 ## Static Analysis
 
 We use [PHPStan](https://phpstan.org) for static analysis.
 
 Run static analysis:
 
 ```sh
-composer stan
+make stan
 ```

Makefile

@@ -0,0 +1,27 @@
+.PHONY: it
+it: fix stan test docs ## Run the commonly used targets
+
+.PHONY: help
+help: ## Displays this list of targets with descriptions
+	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(firstword $(MAKEFILE_LIST)) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: fix
+fix: vendor ## Apply automatic code fixes
+	vendor/bin/php-cs-fixer fix
+
+.PHONY: stan
+stan: vendor ## Runs a static analysis with phpstan
+	vendor/bin/phpstan
+
+.PHONY: test
+test: vendor ## Runs tests with phpunit
+	vendor/bin/phpunit --testsuite=Tests
+	vendor/bin/phpunit --testsuite=Rector
+
+docs: ## Generate documentation
+	vendor/bin/rule-doc-generator generate src/Rector --output-file=rector-rules.md
+
+vendor: composer.json
+	composer validate --strict
+	composer install
+	composer normalize

README.md

@@ -26,9 +26,10 @@ Created by [Ben Sampson](https://sampo.co.uk)
 
 - [Guide](#guide)
 - [Installation](#installation)
+- [Migrate to Native PHP Enums](#migrate-to-native-PHP-enums)
 - [Enum Library](enum-library.md)
 - [Basic Usage](#basic-usage)
-  - [Enum definition](#enum-definition)
+  - [Enum Definition](#enum-definition)
   - [Instantiation](#instantiation)
   - [Instance Properties](#instance-properties)
   - [Instance Equality](#instance-equality)
@@ -38,7 +39,9 @@ Created by [Ben Sampson](https://sampo.co.uk)
 - [Migrations](#migrations)
 - [Validation](#validation)
 - [Localization](#localization)
-- [Customizing descriptions](#customizing-descriptions)
+- [Customizing Descriptions](#customizing-descriptions)
+  - [Customizing Class Description](#customizing-class-description)
+  - [Customizing Value Descriptions](#customizing-value-descriptions)
 - [Extending the Enum Base Class](#extending-the-enum-base-class)
 - [Laravel Nova Integration](#laravel-nova-integration)
 - [PHPStan Integration](#phpstan-integration)
@@ -54,25 +57,42 @@ You are reading the documentation for `6.x`.
 - If you're using **Laravel 7** please see the [docs for `2.x`](https://github.com/BenSampo/laravel-enum/blob/v2.2.0/README.md).
 - If you're using **Laravel 6** or below, please see the [docs for `1.x`](https://github.com/BenSampo/laravel-enum/blob/v1.38.0/README.md).
 
-Please see the [upgrade guide](./UPGRADE.md) for information on how to upgrade to the latest version.
+Please see the [upgrade guide](UPGRADE.md) for information on how to upgrade to the latest version.
 
 ## Guide
 
 I wrote a blog post about using laravel-enum: https://sampo.co.uk/blog/using-enums-in-laravel
 
 ## Installation
 
-### Requirements
+Requires PHP 8, and Laravel 9 or 10.
 
-- Laravel `9` or higher
-- PHP `8.0` or higher
-
-Via Composer
-
-```bash
+```sh
 composer require bensampo/laravel-enum
 ```
 
+## Migrate to Native PHP Enums
+
+PHP 8.1 supports enums natively.
+You can migrate your usages of `BenSampo\Enum\Enum` to native PHP enums using the following steps.
+
+For large projects, it is recommended to migrate one enum at a time. 
+Conversion of enums and their usages can not be done in a single run of rector,
+that would leave the project partially converted.
+Usages seen after the enum classes have been converted will no longer be transformed.
+
+1. Configure the enum class you want to convert in [`ToNativeUsagesRector`](rector-rules.md#tonativeusagesrector)
+   and run `vendor/bin/rector process --clear-cache` once.
+   Running repeatedly messes up the conversion.
+1. Switch the rector to [`ToNativeImplementationRector`](rector-rules.md#tonativeimplementationrector) 
+   and run `vendor/bin/rector process --clear-cache` once again.
+   If you have just one or a few classes, you may pass their paths to speed this up.
+1. Review and validate the code changes for missed edge cases
+   - See [Unimplemented](tests/Rector/Unimplemented)
+   - `Enum::coerce()`: If only values were passed, you can replace it with `tryFrom()`.
+      If keys or instances could also be passed, you might need additional logic to cover this.
+   - `Enum::getDescription()`: Implement an alternative.
+
 ## Enum Library
 
 Browse and download from a list of commonly used, community contributed enums.
@@ -144,15 +164,15 @@ $enumInstance = UserType::coerce($someValue);
 If you want your IDE to autocomplete the static instantiation helpers, you can
 generate PHPDoc annotations through an artisan command.
 
-By default all Enums in `app/Enums` will be annotated (you can change the folder by passing a path to `--folder`)
+By default, all Enums in `app/Enums` will be annotated (you can change the folder by passing a path to `--folder`).
 
-```bash
+```sh
 php artisan enum:annotate
 ```
 
-You can annotate a single class by specifying the class name
+You can annotate a single class by specifying the class name.
 
-```bash
+```sh
 php artisan enum:annotate "App\Enums\UserType"
 ```
 
@@ -768,7 +788,9 @@ final class UserType extends Enum implements LocalizedEnum
 
 The `getDescription` method will now look for the value in your localization files. If a value doesn't exist for a given key, the default description is returned instead.
 
-## Customizing enum class description
+## Customizing descriptions
+
+### Customizing class description
 
 If you'd like to return a custom description for your enum class, add a `Description` attribute to your Enum class:
 
@@ -787,7 +809,7 @@ Calling `UserType::getClassDescription()` now returns `List of available User ty
 
 You may also override the `getClassDescription` method on the base Enum class if you wish to have more control of the description.
 
-## Customizing value descriptions
+### Customizing value descriptions
 
 If you'd like to return a custom description for your enum values, add a `Description` attribute to your Enum constants:
 
@@ -828,7 +850,7 @@ It's best to register the macro inside a service providers' boot method.
 
 Use the [nova-enum-field](https://github.com/simplesquid/nova-enum-field) package by Simple Squid to easily create fields for your Enums in Nova. See their readme for usage.
 
-## PHPStan integration
+## PHPStan Integration
 
 If you are using [PHPStan](https://github.com/phpstan/phpstan) for static
 analysis, you can enable the extension for proper recognition of the
@@ -855,7 +877,7 @@ Generate DocBlock annotations for enum classes.
 
 ### `php artisan enum:to-native`
 
-Convert a class that extends `BenSampo\Enum\Enum` to a native PHP enum.
+Deprecated, see [migrate to native PHP enums](#migrate-to-native-php-enums).
 
 ## Enum Class Reference
 

composer.json

@@ -36,12 +36,14 @@
         "ergebnis/composer-normalize": "^2.28.3",
         "mll-lab/php-cs-fixer-config": "^5.4",
         "mockery/mockery": "^1.5",
-        "nunomaduro/larastan": "^2.1.12",
+        "nunomaduro/larastan": "^2.6.3",
         "orchestra/testbench": "^7.6.1 || ^8",
         "phpstan/phpstan": "^1.8.2",
         "phpstan/phpstan-mockery": "^1.1",
         "phpstan/phpstan-phpunit": "^1.1.1",
-        "phpunit/phpunit": "^9.5.21"
+        "phpunit/phpunit": "^9.5.21 || ^10",
+        "rector/rector": "^0.17.6",
+        "symplify/rule-doc-generator": "^11"
     },
     "minimum-stability": "dev",
     "prefer-stable": true,
@@ -76,15 +78,6 @@
     "scripts": {
         "post-autoload-dump": [
             "@php vendor/bin/testbench package:discover"
-        ],
-        "all": [
-            "composer normalize",
-            "@fix",
-            "@test",
-            "@stan"
-        ],
-        "fix": "php-cs-fixer fix",
-        "stan": "phpstan",
-        "test": "phpunit"
+        ]
     }
 }

phpunit.xml

@@ -1,21 +1,20 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit backupGlobals="false"
-         backupStaticAttributes="false"
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
          bootstrap="vendor/autoload.php"
-         colors="true"
-         convertErrorsToExceptions="true"
-         convertNoticesToExceptions="true"
-         convertWarningsToExceptions="true"
-         processIsolation="false"
-         stopOnFailure="false"
-        >
-    <testsuites>
-        <testsuite name="Laravel Enum Test Suite">
-            <directory suffix="Test.php">./tests/</directory>
-        </testsuite>
-    </testsuites>
-    <php>
-        <env name="DB_CONNECTION" value="sqlite"/>
-        <env name="DB_DATABASE" value=":memory:"/>
-    </php>
+         colors="true">
+  <testsuites>
+    <!-- We have to separate those testsuites due to a conflict when requiring PhpParser, see https://github.com/rectorphp/rector/issues/6709 -->
+    <testsuite name="Tests">
+      <directory>tests</directory>
+      <exclude>tests/Rector</exclude>
+    </testsuite>
+    <testsuite name="Rector">
+      <directory>tests/Rector</directory>
+    </testsuite>
+  </testsuites>
+  <php>
+    <env name="DB_CONNECTION" value="sqlite"/>
+    <env name="DB_DATABASE" value=":memory:"/>
+  </php>
 </phpunit>

rector-rules.md

@@ -0,0 +1,81 @@
+# 2 Rules Overview
+
+## ToNativeImplementationRector
+
+Convert usages of `BenSampo\Enum\Enum` to native PHP enums
+
+:wrench: **configure it!**
+
+- class: [`BenSampo\Enum\Rector\ToNativeImplementationRector`](src/Rector/ToNativeImplementationRector.php)
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use BenSampo\Enum\Rector\ToNativeImplementationRector;
+use BenSampo\Enum\Tests\Enums\UserType;
+use Rector\Config\RectorConfig;
+
+return static function (RectorConfig $rectorConfig): void {
+    $rectorConfig->ruleWithConfiguration(ToNativeImplementationRector::class, [
+        UserType::class,
+    ]);
+};
+```
+
+↓
+
+```diff
+-/**
+- * @method static static ADMIN()
+- * @method static static MEMBER()
+- *
+- * @extends Enum<int>
+- */
+-class UserType extends Enum
++enum UserType : int
+ {
+-    const ADMIN = 1;
+-    const MEMBER = 2;
++    case ADMIN = 1;
++    case MEMBER = 2;
+ }
+```
+
+<br>
+
+## ToNativeUsagesRector
+
+Convert usages of `BenSampo\Enum\Enum` to native PHP enums
+
+:wrench: **configure it!**
+
+- class: [`BenSampo\Enum\Rector\ToNativeUsagesRector`](src/Rector/ToNativeUsagesRector.php)
+
+```php
+<?php
+
+declare(strict_types=1);
+
+use BenSampo\Enum\Rector\ToNativeUsagesRector;
+use BenSampo\Enum\Tests\Enums\UserType;
+use Rector\Config\RectorConfig;
+
+return static function (RectorConfig $rectorConfig): void {
+    $rectorConfig->ruleWithConfiguration(ToNativeUsagesRector::class, [
+        UserType::class,
+    ]);
+};
+```
+
+↓
+
+```diff
+-$user = UserType::ADMIN();
+-$user->is(UserType::ADMIN);
++$user = UserType::ADMIN;
++$user === UserType::ADMIN;
+```
+
+<br>