Add translation() => getOrCreateTranslation() rector rule for 6.x

In CakePHP 6.0, TranslateTrait::translation() becomes a pure getter
that returns null if no translation exists. The old create-on-access
behavior is now in getOrCreateTranslation().

This rector transforms $entity->translation('lang') calls to
$entity->getOrCreateTranslation('lang') to preserve backward
compatibility during the upgrade.

See: cakephp/cakephp#19251

Author: dereuromark

config/rector/sets/cakephp60.php

@@ -0,0 +1,10 @@
+<?php
+declare(strict_types=1);
+
+use Cake\Upgrade\Rector\Rector\MethodCall\TranslationToGetOrCreateTranslationRector;
+use Rector\Config\RectorConfig;
+
+# @see https://book.cakephp.org/6/en/appendices/6-0-migration-guide.html
+return static function (RectorConfig $rectorConfig): void {
+    $rectorConfig->rule(TranslationToGetOrCreateTranslationRector::class);
+};

src/Rector/Rector/MethodCall/TranslationToGetOrCreateTranslationRector.php

@@ -0,0 +1,71 @@
+<?php
+declare(strict_types=1);
+
+namespace Cake\Upgrade\Rector\Rector\MethodCall;
+
+use Cake\ORM\Entity;
+use PhpParser\Node;
+use PhpParser\Node\Expr\MethodCall;
+use PhpParser\Node\Identifier;
+use PHPStan\Type\ObjectType;
+use Rector\Rector\AbstractRector;
+use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
+use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
+
+/**
+ * Renames translation() to getOrCreateTranslation() for entities using TranslateTrait.
+ *
+ * In CakePHP 6.0, translation() became a pure getter that returns null if no translation exists.
+ * The old create-on-access behavior is now in getOrCreateTranslation().
+ *
+ * @see https://github.com/cakephp/cakephp/pull/19251
+ */
+final class TranslationToGetOrCreateTranslationRector extends AbstractRector
+{
+    public function getRuleDefinition(): RuleDefinition
+    {
+        return new RuleDefinition(
+            'Rename $entity->translation() to $entity->getOrCreateTranslation() to preserve create-on-access behavior',
+            [
+                new CodeSample(
+                    <<<'CODE_SAMPLE'
+$article->translation('fra');
+CODE_SAMPLE
+                    ,
+                    <<<'CODE_SAMPLE'
+$article->getOrCreateTranslation('fra');
+CODE_SAMPLE,
+                ),
+            ],
+        );
+    }
+
+    public function getNodeTypes(): array
+    {
+        return [MethodCall::class];
+    }
+
+    public function refactor(Node $node): ?Node
+    {
+        if (!$node instanceof MethodCall) {
+            return null;
+        }
+
+        if (!$this->isName($node->name, 'translation')) {
+            return null;
+        }
+
+        $objectType = $this->getType($node->var);
+        if (!$objectType instanceof ObjectType) {
+            return null;
+        }
+
+        if (!$objectType->isInstanceOf(Entity::class)->yes()) {
+            return null;
+        }
+
+        $node->name = new Identifier('getOrCreateTranslation');
+
+        return $node;
+    }
+}

src/Rector/Set/CakePHPSetList.php

@@ -85,6 +85,11 @@ final class CakePHPSetList
      */
     public const CAKEPHP_53 = __DIR__ . '/../../../config/rector/sets/cakephp53.php';
 
+    /**
+     * @var string
+     */
+    public const CAKEPHP_60 = __DIR__ . '/../../../config/rector/sets/cakephp60.php';
+
     /**
      * @var string
      */

tests/TestCase/Rector/MethodCall/TranslationToGetOrCreateTranslationRector/Fixture/fixture.php.inc

@@ -0,0 +1,49 @@
+<?php
+
+namespace Cake\Upgrade\Test\TestCase\Rector\MethodCall\TranslationToGetOrCreateTranslationRector\Fixture;
+
+use Cake\ORM\Entity;
+
+class Article extends Entity
+{
+}
+
+class ArticlesController
+{
+    public function edit()
+    {
+        $article = new Article();
+
+        // Should transform: Entity->translation()
+        $translation = $article->translation('fra');
+
+        return $article;
+    }
+}
+
+?>
+-----
+<?php
+
+namespace Cake\Upgrade\Test\TestCase\Rector\MethodCall\TranslationToGetOrCreateTranslationRector\Fixture;
+
+use Cake\ORM\Entity;
+
+class Article extends Entity
+{
+}
+
+class ArticlesController
+{
+    public function edit()
+    {
+        $article = new Article();
+
+        // Should transform: Entity->translation()
+        $translation = $article->getOrCreateTranslation('fra');
+
+        return $article;
+    }
+}
+
+?>

tests/TestCase/Rector/MethodCall/TranslationToGetOrCreateTranslationRector/Fixture/skip_non_entity.php.inc

@@ -0,0 +1,26 @@
+<?php
+
+namespace Cake\Upgrade\Test\TestCase\Rector\MethodCall\TranslationToGetOrCreateTranslationRector\Fixture;
+
+class SomeTranslationService
+{
+    public function translation(string $lang): ?string
+    {
+        return null;
+    }
+}
+
+class SomeController
+{
+    public function index()
+    {
+        $service = new SomeTranslationService();
+
+        // Should NOT transform: not an Entity subclass
+        $result = $service->translation('fra');
+
+        return $result;
+    }
+}
+
+?>

tests/TestCase/Rector/MethodCall/TranslationToGetOrCreateTranslationRector/TranslationToGetOrCreateTranslationRectorTest.php

@@ -0,0 +1,28 @@
+<?php
+declare(strict_types=1);
+
+namespace Cake\Upgrade\Test\TestCase\Rector\MethodCall\TranslationToGetOrCreateTranslationRector;
+
+use Iterator;
+use Rector\Testing\PHPUnit\AbstractRectorTestCase;
+
+final class TranslationToGetOrCreateTranslationRectorTest extends AbstractRectorTestCase
+{
+    /**
+     * @dataProvider provideData()
+     */
+    public function test(string $filePath): void
+    {
+        $this->doTestFile($filePath);
+    }
+
+    public static function provideData(): Iterator
+    {
+        return self::yieldFilesFromDirectory(__DIR__ . '/Fixture');
+    }
+
+    public function provideConfigFilePath(): string
+    {
+        return __DIR__ . '/config/configured_rule.php';
+    }
+}

tests/TestCase/Rector/MethodCall/TranslationToGetOrCreateTranslationRector/config/configured_rule.php

@@ -0,0 +1,9 @@
+<?php
+declare(strict_types=1);
+
+use Cake\Upgrade\Rector\Rector\MethodCall\TranslationToGetOrCreateTranslationRector;
+use Rector\Config\RectorConfig;
+
+return static function (RectorConfig $rectorConfig): void {
+    $rectorConfig->rule(TranslationToGetOrCreateTranslationRector::class);
+};