Generic/UpperCaseConstantName: skip when local define() is in scope

When a file declares a top-level `function define(...)` or imports one
via `use function ...\define;` (including group use and `as` aliases),
unqualified `define(...)` calls may resolve to that function instead of
the global one. The sniff should bow out in those cases.

Fully qualified `\define(...)` calls remain checked as before because
they tokenize as T_NAME_FULLY_QUALIFIED and unambiguously refer to the
global function.

Fixes #733

Author: dereuromark

src/Standards/Generic/Sniffs/NamingConventions/UpperCaseConstantNameSniff.php

@@ -103,6 +103,17 @@ public function process(File $phpcsFile, int $stackPtr)
             return;
         }
 
+        // If the file declares or imports a function named "define",
+        // any unqualified `define()` call may resolve to that function
+        // instead of the global one, so the sniff should bow out.
+        // Fully qualified `\define(...)` calls are unaffected as they
+        // come in as T_NAME_FULLY_QUALIFIED tokens and are handled below.
+        if ($tokens[$stackPtr]['code'] === T_STRING
+            && $this->fileHasCustomDefine($phpcsFile) === true
+        ) {
+            return;
+        }
+
         // If the next non-whitespace token after this token
         // is not an opening parenthesis then it is not a function call.
         $openBracket = $phpcsFile->findNext(Tokens::EMPTY_TOKENS, ($stackPtr + 1), null, true);
@@ -146,4 +157,142 @@ public function process(File $phpcsFile, int $stackPtr)
             $phpcsFile->recordMetric($constPtr, 'Constant name case', 'upper');
         }
     }
+
+
+    /**
+     * Determine whether a file declares or imports a function named "define".
+     *
+     * Checks for top-level `function define(...)` declarations and
+     * `use function ...\define;` (or aliased) imports. The result is cached
+     * per file path to avoid rescanning on every visited token.
+     *
+     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
+     *
+     * @return bool
+     */
+    private function fileHasCustomDefine(File $phpcsFile)
+    {
+        static $cache = [];
+
+        $fileKey = $phpcsFile->getFilename();
+        if (isset($cache[$fileKey]) === true) {
+            return $cache[$fileKey];
+        }
+
+        $tokens = $phpcsFile->getTokens();
+        $result = false;
+
+        for ($i = 0; $i < $phpcsFile->numTokens; $i++) {
+            $code = $tokens[$i]['code'];
+
+            // Top-level `function define(...)` declaration.
+            if ($code === T_FUNCTION && empty($tokens[$i]['conditions']) === true) {
+                $namePtr = $phpcsFile->findNext(Tokens::EMPTY_TOKENS, ($i + 1), null, true);
+                if ($namePtr !== false
+                    && $tokens[$namePtr]['code'] === T_STRING
+                    && strtolower($tokens[$namePtr]['content']) === 'define'
+                ) {
+                    $result = true;
+                    break;
+                }
+
+                continue;
+            }
+
+            // `use function ...define;` import (only top-level use statements).
+            if ($code === T_USE && empty($tokens[$i]['conditions']) === true) {
+                $next = $phpcsFile->findNext(Tokens::EMPTY_TOKENS, ($i + 1), null, true);
+                if ($next === false || $tokens[$next]['code'] !== T_STRING
+                    || strtolower($tokens[$next]['content']) !== 'function'
+                ) {
+                    continue;
+                }
+
+                $end = $phpcsFile->findNext([T_SEMICOLON, T_OPEN_USE_GROUP], ($next + 1));
+                if ($end === false) {
+                    continue;
+                }
+
+                if ($this->useListImportsDefine($phpcsFile, $next, $end) === true) {
+                    $result = true;
+                    break;
+                }
+
+                // Group use statement: walk the body looking for a `define` import.
+                if ($tokens[$end]['code'] === T_OPEN_USE_GROUP) {
+                    $groupEnd = $phpcsFile->findNext(T_CLOSE_USE_GROUP, ($end + 1));
+                    if ($groupEnd !== false
+                        && $this->useListImportsDefine($phpcsFile, $end, $groupEnd) === true
+                    ) {
+                        $result = true;
+                        break;
+                    }
+                }
+            }
+        }
+
+        $cache[$fileKey] = $result;
+
+        return $result;
+    }
+
+
+    /**
+     * Inspect a `use function` import list for a `define` import.
+     *
+     * Handles plain imports (`use function Foo\define;`), aliases away from
+     * `define` (`use function Foo\define as something;` — does NOT count) and
+     * aliases to `define` (`use function Foo\bar as define;` — counts).
+     *
+     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
+     * @param int                         $start     Position to start scanning after.
+     * @param int                         $end       Position to stop scanning at.
+     *
+     * @return bool
+     */
+    private function useListImportsDefine(File $phpcsFile, int $start, int $end)
+    {
+        $tokens = $phpcsFile->getTokens();
+
+        for ($j = ($start + 1); $j < $end; $j++) {
+            $code = $tokens[$j]['code'];
+
+            // Explicit alias: `... as define`.
+            if ($code === T_AS) {
+                $aliasPtr = $phpcsFile->findNext(Tokens::EMPTY_TOKENS, ($j + 1), $end, true);
+                if ($aliasPtr !== false
+                    && $tokens[$aliasPtr]['code'] === T_STRING
+                    && strtolower($tokens[$aliasPtr]['content']) === 'define'
+                ) {
+                    return true;
+                }
+
+                continue;
+            }
+
+            if ($code !== T_STRING
+                && $code !== T_NAME_QUALIFIED
+                && $code !== T_NAME_FULLY_QUALIFIED
+            ) {
+                continue;
+            }
+
+            $segments = explode('\\', $tokens[$j]['content']);
+            $last     = strtolower(end($segments));
+            if ($last !== 'define') {
+                continue;
+            }
+
+            // Skip if the next non-empty token is `as` — the import is renamed
+            // and is therefore not in scope as `define`.
+            $after = $phpcsFile->findNext(Tokens::EMPTY_TOKENS, ($j + 1), $end, true);
+            if ($after !== false && $tokens[$after]['code'] === T_AS) {
+                continue;
+            }
+
+            return true;
+        }
+
+        return false;
+    }
 }

src/Standards/Generic/Tests/NamingConventions/UpperCaseConstantNameUnitTest.1.inc

@@ -79,9 +79,6 @@ define(condition() ? 'name1' : 'name2', 'sniff should bow out');
 
 $callable = define(...);
 
-// Valid if outside the global namespace. Sniff should bow out.
-function define($param) {}
-
 class MyClass {
     public function define($param) {}
 }

src/Standards/Generic/Tests/NamingConventions/UpperCaseConstantNameUnitTest.6.inc

@@ -0,0 +1,22 @@
+<?php
+
+namespace Foo;
+
+// These are calls to the namespaced function `Foo\define()`,
+// which is declared further down in the file.
+define('name', 'value');
+namespace\define('name', 'value');
+
+// These are calls to other namespaced functions, never the global one.
+Sub\define('name', 'value');
+\My\Other\NS\define('name', 'value');
+
+// Calls to the global function via the leading backslash MUST still be checked.
+\define('VALID_NAME', true);
+
+// Lowercase here SHOULD be flagged: the leading backslash forces global resolution.
+\define('lowercase_global', 'value');
+
+function define($name, $value) {
+    // Do something.
+}

src/Standards/Generic/Tests/NamingConventions/UpperCaseConstantNameUnitTest.7.inc

@@ -0,0 +1,12 @@
+<?php
+
+namespace Foo;
+
+use function Bar\define;
+use function Bar\{otherFunc, define as renamedDefine};
+
+// This is a call to the imported namespaced function, not the global one.
+define('name', 'value');
+
+// Lowercase here SHOULD be flagged: the leading backslash forces global resolution.
+\define('lowercase_global', 'value');

src/Standards/Generic/Tests/NamingConventions/UpperCaseConstantNameUnitTest.8.inc

@@ -0,0 +1,8 @@
+<?php
+
+namespace Foo;
+
+// `define` is aliased AWAY: the local symbol is `something`, not `define`.
+use function Bar\define as something;
+
+define('name', 'value');

src/Standards/Generic/Tests/NamingConventions/UpperCaseConstantNameUnitTest.php

@@ -49,7 +49,31 @@ public function getErrorList($testFile = '')
                     51 => 1,
                     71 => 1,
                     73 => 1,
-                    94 => 1,
+                    91 => 1,
+                ];
+
+            case 'UpperCaseConstantNameUnitTest.6.inc':
+                return [
+                    // Only the fully qualified `\define()` call should be flagged;
+                    // the unqualified `define()` calls may resolve to the local
+                    // `Foo\define` function declared further down in the file.
+                    18 => 1,
+                ];
+
+            case 'UpperCaseConstantNameUnitTest.7.inc':
+                return [
+                    // `use function Bar\define;` brings a `define` symbol into scope,
+                    // so unqualified `define()` calls must not be flagged. Only the
+                    // fully qualified `\define()` call is.
+                    12 => 1,
+                ];
+
+            case 'UpperCaseConstantNameUnitTest.8.inc':
+                return [
+                    // `use function Bar\define as something;` aliases AWAY from
+                    // `define`, so the local `define` symbol is unaffected and
+                    // unqualified `define()` calls should still be flagged.
+                    8 => 1,
                 ];
 
             default: