Merge pull request #78 from ray-di/remove-doctrine-annotations

Remove doctrine/annotations dependency

Author: koriym

.scrutinizer.yml

@@ -0,0 +1,12 @@
+build:
+    image: default-jammy
+    environment:
+        php: 8.4
+    nodes:
+        analysis:
+            tests:
+                override:
+                    - php-scrutinizer-run
+
+filter:
+    paths: ["src/*"]

ANNOTATION_TO_ATTRIBUTE.md

@@ -0,0 +1,220 @@
+# Migrating from Doctrine Annotations to PHP 8 Attributes
+
+## Overview
+
+Ray.AuraSqlModule v2.x has removed the dependency on `doctrine/annotations` and now exclusively uses native PHP 8 attributes. This guide will help you migrate your application code from Doctrine annotations to PHP 8 attributes.
+
+## Why Migrate?
+
+- **doctrine/annotations is Abandoned**: The `doctrine/annotations` package has been officially abandoned by its maintainers. Continuing to use it poses security and compatibility risks as it will no longer receive updates or security patches.
+- **Native PHP Support**: PHP 8 attributes are a built-in language feature, providing first-class support without external dependencies
+- **Better Performance**: No runtime annotation parsing overhead - attributes are compiled and cached by PHP itself
+- **Modern Syntax**: Cleaner, more readable code that follows PHP 8+ best practices
+- **No Extra Dependencies**: Eliminates the need for the abandoned doctrine/annotations package
+- **Future-Proof**: Attributes are the official PHP standard for metadata, ensuring long-term compatibility
+
+## Migration Steps
+
+### Step 1: Update Ray.AuraSqlModule
+
+First, ensure you're using Ray.AuraSqlModule v2.x:
+
+```bash
+composer require ray/aura-sql-module:^2.0
+```
+
+### Step 2: Install Rector (if not already installed)
+
+Rector is an automated refactoring tool that can convert annotations to attributes:
+
+```bash
+composer require --dev rector/rector
+```
+
+### Step 3: Run Automated Migration
+
+Ray.AuraSqlModule provides a Rector configuration file for automated migration:
+
+```bash
+# Dry-run to preview changes
+vendor/bin/rector process src --config=vendor/ray/aura-sql-module/rector-migrate.php --dry-run
+
+# Apply the changes
+vendor/bin/rector process src --config=vendor/ray/aura-sql-module/rector-migrate.php
+```
+
+If you have tests that use annotations:
+
+```bash
+vendor/bin/rector process tests --config=vendor/ray/aura-sql-module/rector-migrate.php
+```
+
+### Step 4: Manual Review
+
+Review the changes made by Rector and adjust if necessary. Pay special attention to:
+
+- Multi-line annotations with complex values
+- Annotations with custom parameters
+- Import statements (Rector should handle these automatically)
+
+### Step 5: Remove doctrine/annotations
+
+After migration, you can safely remove the doctrine/annotations dependency:
+
+```bash
+composer remove doctrine/annotations
+```
+
+## Before and After Examples
+
+### Transactional Annotation
+
+**Before (Doctrine Annotation):**
+```php
+use Ray\AuraSqlModule\Annotation\Transactional;
+use Ray\AuraSqlModule\Annotation\WriteConnection;
+
+class UserRepository
+{
+    /**
+     * @WriteConnection
+     * @Transactional
+     */
+    public function save(User $user): void
+    {
+        // ...
+    }
+}
+```
+
+**After (PHP 8 Attribute):**
+```php
+use Ray\AuraSqlModule\Annotation\Transactional;
+use Ray\AuraSqlModule\Annotation\WriteConnection;
+
+class UserRepository
+{
+    #[WriteConnection, Transactional]
+    public function save(User $user): void
+    {
+        // ...
+    }
+}
+```
+
+### Read-Only Connection
+
+**Before (Doctrine Annotation):**
+```php
+use Aura\Sql\ExtendedPdoInterface;
+use Ray\AuraSqlModule\Annotation\ReadOnlyConnection;
+
+class UserFinder
+{
+    /**
+     * @ReadOnlyConnection
+     */
+    public function __construct(
+        private ExtendedPdoInterface $pdo
+    ) {}
+}
+```
+
+**After (PHP 8 Attribute):**
+```php
+use Aura\Sql\ExtendedPdoInterface;
+use Ray\AuraSqlModule\Annotation\ReadOnlyConnection;
+
+class UserFinder
+{
+    #[ReadOnlyConnection]
+    public function __construct(
+        private ExtendedPdoInterface $pdo
+    ) {}
+}
+```
+
+## Supported Annotations
+
+The following Ray.AuraSqlModule annotations are automatically converted:
+
+- `@Transactional` → `#[Transactional]`
+- `@WriteConnection` → `#[WriteConnection]`
+- `@ReadOnlyConnection` → `#[ReadOnlyConnection]`
+- `@Read` → `#[Read]`
+- `@AuraSql` → `#[AuraSql]`
+- `@EnvAuth` → `#[EnvAuth]`
+- `@HttpMethod` → `#[HttpMethod]`
+- `@PagerViewOption` → `#[PagerViewOption]`
+- `@AuraSqlQueryConfig` → `#[AuraSqlQueryConfig]`
+
+**Note**: This migration tool only handles Ray.AuraSqlModule annotations. For Ray.Di annotations (such as `@Inject`, `@Named`, etc.), please refer to the [Ray.Di migration guide](https://github.com/ray-di/Ray.Di).
+
+## Troubleshooting
+
+### Rector doesn't find annotations
+
+Make sure your code is using fully qualified class names in `use` statements:
+
+```php
+// Correct
+use Ray\AuraSqlModule\Annotation\Transactional;
+
+// Incorrect - Rector won't recognize this
+use Ray\AuraSqlModule\Annotation as DB;
+```
+
+### Import statements not updated
+
+Rector should automatically update import statements, but if it doesn't:
+
+1. Manually verify `use` statements are present
+2. Run your IDE's "Optimize Imports" feature
+3. Use tools like PHP-CS-Fixer to clean up unused imports
+
+### Complex annotation values
+
+For annotations with complex array values, you may need to manually adjust the syntax:
+
+**Before:**
+```php
+/**
+ * @Transactional({"pdo1", "pdo2"})
+ */
+```
+
+**After:**
+```php
+#[Transactional(["pdo1", "pdo2"])]
+```
+
+### Testing the migration
+
+After migration, ensure all tests pass:
+
+```bash
+vendor/bin/phpunit
+```
+
+## Manual Migration
+
+If you prefer not to use Rector, you can manually convert annotations:
+
+1. Replace `/** @AnnotationName */` with `#[AnnotationName]`
+2. Move attributes from docblocks to the line before the method/property/class
++3. For parameter annotations, place the attribute before the parameter declaration
+4. Ensure all necessary `use` statements are present
+
+## Need Help?
+
+If you encounter issues during migration:
+
+1. Check the [Ray.AuraSqlModule documentation](https://github.com/ray-di/Ray.AuraSqlModule)
+2. Review the [PHP 8 Attributes documentation](https://www.php.net/manual/en/language.attributes.php)
+3. [Open an issue](https://github.com/ray-di/Ray.AuraSqlModule/issues) on GitHub
+
+## References
+
+- [PHP 8 Attributes RFC](https://wiki.php.net/rfc/attributes_v2)
+- [Rector Documentation](https://github.com/rectorphp/rector)
+- [Ray.Di Documentation](https://ray-di.github.io/manuals/1.0/en/)

CHANGELOG.md

@@ -1,9 +1,17 @@
-## [1.18.0]
+## [1.15.0] - 2025-11-09
 
 ### Changed
-- Updated Aura.Sql dependency from ^5.0 to ^6.0 for PHP 8.4 compatibility
-- Internal PDO handling improvements for PHP 8.4
+- **PHP 8.4 Requirement**: Updated minimum PHP version to ^8.4
+- **Aura.Sql v6**: Updated dependency from ^5.0 to ^6.0 for PHP 8.4 compatibility
+- **Removed doctrine/annotations**: Eliminated abandoned dependency, migrated to native PHP 8 attributes
+- **Code Modernization**: Applied Rector refactoring for cleaner, modern PHP 8.4 code
+
+### Added
+- **Migration Tools**: Added `rector-migrate.php` for automated annotation-to-attribute migration
+- **Migration Guide**: Added `ANNOTATION_TO_ATTRIBUTE.md` with comprehensive migration instructions
+- **CI Enhancement**: Added Scrutinizer CI configuration for automated code quality analysis
 
 ### Note
-- **No code changes required** - all APIs remain identical
-- Automatic compatibility with both PHP 8.1-8.3 (Aura.Sql v5) and PHP 8.4+ (Aura.Sql v6)
+- **Migration Required**: Applications using annotations must migrate to PHP 8 attributes
+- Use provided Rector configuration for automated migration: `vendor/bin/rector process src --config=vendor/ray/aura-sql-module/rector-migrate.php`
+- See `ANNOTATION_TO_ATTRIBUTE.md` for detailed migration guide

composer.json

@@ -15,7 +15,6 @@
         "aura/sql": "^6.0",
         "pagerfanta/pagerfanta": "^3.5 || ^4.7",
         "rize/uri-template": "^0.4",
-        "doctrine/annotations": "^1.11 || ^2.0",
         "psr/log": "^1.1 || ^2.0 || ^3.0",
         "aura/sqlquery": "^3.0"
     },

rector-migrate.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+use Rector\Config\RectorConfig;
+use Rector\Php80\Rector\Class_\AnnotationToAttributeRector;
+use Rector\Php80\ValueObject\AnnotationToAttribute;
+
+/**
+ * Rector configuration for migrating from Doctrine Annotations to PHP 8 Attributes
+ *
+ * This configuration helps users migrate their code from doctrine/annotations
+ * to native PHP 8 attributes for Ray.AuraSqlModule annotations.
+ *
+ * Usage:
+ *   vendor/bin/rector process src --config=rector-migrate.php --dry-run
+ *   vendor/bin/rector process src --config=rector-migrate.php
+ */
+return RectorConfig::configure()
+    ->withPaths([
+        __DIR__ . '/src',
+        __DIR__ . '/tests',
+    ])
+    ->withConfiguredRule(
+        AnnotationToAttributeRector::class,
+        [
+            // Ray.AuraSqlModule Annotations
+            new AnnotationToAttribute('Ray\AuraSqlModule\Annotation\Transactional'),
+            new AnnotationToAttribute('Ray\AuraSqlModule\Annotation\WriteConnection'),
+            new AnnotationToAttribute('Ray\AuraSqlModule\Annotation\ReadOnlyConnection'),
+            new AnnotationToAttribute('Ray\AuraSqlModule\Annotation\Read'),
+            new AnnotationToAttribute('Ray\AuraSqlModule\Annotation\AuraSql'),
+            new AnnotationToAttribute('Ray\AuraSqlModule\Annotation\EnvAuth'),
+            new AnnotationToAttribute('Ray\AuraSqlModule\Annotation\HttpMethod'),
+            new AnnotationToAttribute('Ray\AuraSqlModule\Annotation\PagerViewOption'),
+            new AnnotationToAttribute('Ray\AuraSqlModule\Annotation\AuraSqlQueryConfig'),
+        ]
+    );

rector.php

@@ -11,15 +11,7 @@
         __DIR__ . '/src-files',
         __DIR__ . '/tests',
     ])
-    // uncomment to reach your current PHP version
     ->withPhpSets()
-    ->withSets(
-        [
-            PHPUnitSetList::PHPUNIT_90,
-            PHPUnitSetList::PHPUNIT_100,
-            PHPUnitSetList::PHPUNIT_110,
-        ]
-    )
-    ->withTypeCoverageLevel(0)
-    ->withDeadCodeLevel(0)
-    ->withCodeQualityLevel(0);
+    ->withTypeCoverageLevel(1)
+    ->withDeadCodeLevel(1)
+    ->withCodeQualityLevel(1);

src/Annotation/AuraSql.php

@@ -6,10 +6,6 @@
 
 use Attribute;
 
-/**
- * @Annotation
- * @Target("CLASS")
- */
 #[Attribute(Attribute::TARGET_CLASS)]
 final class AuraSql
 {

src/Annotation/AuraSqlQueryConfig.php

@@ -5,15 +5,8 @@
 namespace Ray\AuraSqlModule\Annotation;
 
 use Attribute;
-use Doctrine\Common\Annotations\Annotation\NamedArgumentConstructor;
 use Ray\Di\Di\Qualifier;
 
-/**
- * @Annotation
- * @Target("METHOD")
- * @Qualifier
- * @NamedArgumentConstructor
- */
 #[Attribute(Attribute::TARGET_METHOD), Qualifier]
 final class AuraSqlQueryConfig
 {

src/Annotation/EnvAuth.php

@@ -7,11 +7,6 @@
 use Attribute;
 use Ray\Di\Di\Qualifier;
 
-/**
- * @Annotation
- * @Target("METHOD")
- * @Qualifier
- */
 #[Attribute(Attribute::TARGET_METHOD), Qualifier]
 final class EnvAuth
 {

src/Annotation/HttpMethod.php

@@ -6,10 +6,6 @@
 
 use Attribute;
 
-/**
- * @Annotation
- * @Target("METHOD")
- */
 #[Attribute(Attribute::TARGET_METHOD)]
 final class HttpMethod
 {