CakePHP 3用户名大小写不敏感登录认证失效问题排查

你遇到的核心问题是FormAuthenticate会自动添加大小写敏感的Users.username = :c0条件，这个条件和你自定义的LOWER(username)规则同时生效，导致当用户输入的用户名大小写与数据库不一致时，第一个条件就过滤掉了所有匹配结果。下面给出两种可行的解决方案：

方案1：在Auth Finder中移除默认的username条件 #

这种方法无需修改Auth组件核心逻辑，只需在findAuth方法中先清除自动添加的敏感条件，再加入自定义的大小写不敏感规则：

/**
 * @param Query $query
 * @param array $options
 * @return Query
 */
public function findAuth(Query $query, array $options)
{
    // 移除FormAuthenticate自动添加的username等于条件
    $whereClause = $query->clause('where');
    foreach ($whereClause as $key => $condition) {
        // 定位并删除默认的username匹配条件
        if (is_array($condition) && isset($condition['Users.username'])) {
            unset($whereClause[$key]);
            break;
        }
    }
    $query->clause('where', $whereClause);

    // 添加自定义的大小写不敏感查询条件
    return $query->contain(['Contacts'])
        ->where([
            'activated' => 'yes',
            'LOWER(Users.username)' => strtolower($options['username'])
        ]);
}

修改后，查询语句只会保留你定义的LOWER(Users.username)条件，不再受大小写限制。

方案2：自定义Authenticate类（更彻底的逻辑控制） #

如果希望完全掌控用户查询逻辑，可以继承FormAuthenticate类，重写_findUser方法，避免自动添加默认条件：

第一步：创建自定义认证类 #

在src/Auth/CustomFormAuthenticate.php中创建以下文件：

namespace App\Auth;

use Cake\Auth\FormAuthenticate;
use Cake\ORM\Query;
use Cake\Datasource\Locator\LocatorAwareTrait;

class CustomFormAuthenticate extends FormAuthenticate
{
    use LocatorAwareTrait;

    protected function _findUser($username, $password = null)
    {
        $userModel = $this->_config['userModel'];
        $fields = $this->_config['fields'];
        
        // 初始化用户查询
        $query = $this->getTableLocator()->get($userModel)
            ->find()
            ->contain(['Contacts'])
            // 直接添加大小写不敏感的用户名条件
            ->where([
                'LOWER(' . $userModel . '.' . $fields['username'] . ')' => strtolower($username),
                'activated' => 'yes'
            ]);

        // 处理密码验证（如果需要）
        if ($password !== null) {
            $hasher = $this->passwordHasher();
            $query->where(function ($exp) use ($hasher, $password, $fields) {
                return $exp->eq($fields['password'], $hasher->hash($password));
            });
        }

        return $query->first();
    }
}

第二步：修改Auth组件配置 #

在Controller中加载Auth组件时，替换为自定义的认证类：

$this->loadComponent('Auth', [
    'loginAction' => [
        'controller' => 'Users',
        'action' => 'login'
    ],
    'authError' => 'You need to be logged in',
    'authenticate' => [
        'CustomForm' => [ // 使用自定义的认证类
            'fields' => ['username' => 'username', 'password' => 'password'],
        ]
    ],
    'loginRedirect' => [
        'controller' => 'Pages',
        'action' => 'display',
        'home'
    ],
    'logoutRedirect' => [
        'controller' => 'login'
    ]
]);

性能优化建议（针对PostgreSQL） #

为避免LOWER(username)查询导致全表扫描，建议给username字段创建表达式索引：

CREATE INDEX idx_users_lower_username ON users (LOWER(username));

这个索引会预先计算用户名的小写值，大幅提升查询效率。

内容的提问来源于stack exchange，提问作者Bird87 ZA