From bc7519e8128f118c575a866d0e6594ff797d7c76 Mon Sep 17 00:00:00 2001
From: Jasper Smet <josbeir@gmail.com>
Date: Fri, 2 Oct 2026 19:11:39 +0200
Subject: [PATCH] fix: enforce imported class references in the CakePHP preset

---
 README.md                              |  6 ++++++
 cakephp.mago.toml                      |  1 +
 scripts/check-consumer.sh              | 16 ++++++++++++++
 tests/fixer/class-imports.expected.php | 29 ++++++++++++++++++++++++++
 tests/fixer/class-imports.input.php    | 26 +++++++++++++++++++++++
 5 files changed, 78 insertions(+)
 create mode 100644 tests/fixer/class-imports.expected.php
 create mode 100644 tests/fixer/class-imports.input.php

diff --git a/README.md b/README.md
index de979d8..e324cb2 100644
--- a/README.md
+++ b/README.md
@@ -68,11 +68,17 @@ cyclomatic-complexity = { enabled = false }
 "mago-cakephp/function-docblock" = { enabled = false }
 ```
 
+Class references must use imports rather than fully qualified names in executable
+code. The native `no-fully-qualified-global-class-like` rule is enabled at error
+severity; `mago lint --fix` adds imports and shortens references. PHPDoc names
+are unaffected.
+
 ## Responsibility map
 
 | Concern | Owner |
 | --- | --- |
 | PSR-12 layout, braces, imports, quotes, commas, casts and return spacing | Mago formatter with CakePHP settings |
+| Imported class references | Native `no-fully-qualified-global-class-like` rule |
 | Short arrays, braced blocks, short tags, silenced errors, assignments in conditions and redundant syntax | Native Mago rules |
 | Conflicting `empty()`/`isset()`/comparison/named-argument preferences | Disabled by the CakePHP preset |
 | Trait `Trait` suffix | `mago-cakephp/trait-suffix` |
diff --git a/cakephp.mago.toml b/cakephp.mago.toml
index a40a5da..ad0b715 100644
--- a/cakephp.mago.toml
+++ b/cakephp.mago.toml
@@ -50,6 +50,7 @@ no-error-control-operator = { enabled = true, level = "error" }
 no-assign-in-condition = { enabled = true, level = "error", ignore-while-statements = false }
 no-redundant-parentheses = { enabled = true, level = "error" }
 no-redundant-final = { enabled = true, level = "error" }
+no-fully-qualified-global-class-like = { enabled = true, level = "error" }
 no-redundant-use = { enabled = true, level = "error" }
 no-closing-tag = { enabled = true, level = "error" }
 ambiguous-function-call = { enabled = false }
diff --git a/scripts/check-consumer.sh b/scripts/check-consumer.sh
index 5736a95..0111534 100755
--- a/scripts/check-consumer.sh
+++ b/scripts/check-consumer.sh
@@ -17,3 +17,19 @@ mago="$repo_root/vendor/bin/mago"
 "$mago" --workspace "$consumer_dir" extension validate
 "$mago" --workspace "$consumer_dir" format --check
 "$mago" --workspace "$consumer_dir" lint
+
+# The installed preset must reject fully qualified classes without --only or
+# --pedantic, then apply an exact, idempotent native fix. PHPDoc stays unchanged.
+cp "$repo_root/tests/fixer/class-imports.input.php" "$consumer_dir/src/ClassImports.php"
+if "$mago" --workspace "$consumer_dir" lint --reporting-format short > "$consumer_dir/class-imports.log" 2>&1; then
+    echo "Expected the installed preset to reject fully qualified class references." >&2
+    exit 1
+fi
+if ! grep -q 'error\[no-fully-qualified-global-class-like\]' "$consumer_dir/class-imports.log"; then
+    cat "$consumer_dir/class-imports.log" >&2
+    exit 1
+fi
+"$mago" --workspace "$consumer_dir" lint --fix --format-after-fix --fail-on-remaining
+"$mago" --workspace "$consumer_dir" lint --fix --format-after-fix --fail-on-remaining
+diff -u "$repo_root/tests/fixer/class-imports.expected.php" "$consumer_dir/src/ClassImports.php"
+"$mago" --workspace "$consumer_dir" lint
diff --git a/tests/fixer/class-imports.expected.php b/tests/fixer/class-imports.expected.php
new file mode 100644
index 0000000..c10598d
--- /dev/null
+++ b/tests/fixer/class-imports.expected.php
@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+use Cake\I18n\Date;
+use RuntimeException;
+
+/** Imported references are required in types, construction and static calls. */
+final class ClassImports
+{
+    /** @var \Cake\I18n\Date|null */
+    private ?Date $date = null;
+
+    /** Create a date with an explicit import. */
+    public function date(): Date
+    {
+        $this->date = new Date();
+
+        return $this->date;
+    }
+
+    /** Read the global exception class using an import. */
+    public function exceptionClass(): string
+    {
+        return RuntimeException::class;
+    }
+}
diff --git a/tests/fixer/class-imports.input.php b/tests/fixer/class-imports.input.php
new file mode 100644
index 0000000..f98c704
--- /dev/null
+++ b/tests/fixer/class-imports.input.php
@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App;
+
+/** Imported references are required in types, construction and static calls. */
+final class ClassImports
+{
+    /** @var \Cake\I18n\Date|null */
+    private ?\Cake\I18n\Date $date = null;
+
+    /** Create a date with an explicit import. */
+    public function date(): \Cake\I18n\Date
+    {
+        $this->date = new \Cake\I18n\Date();
+
+        return $this->date;
+    }
+
+    /** Read the global exception class using an import. */
+    public function exceptionClass(): string
+    {
+        return \RuntimeException::class;
+    }
+}