Yii 2.0 存取控制過濾器 (AccessControl) 實戰：游客/用戶/角色權限精準管控

核心概念：AccessControl 行為過濾器

Yii 2 內建 yii\filters\AccessControl，透過規則陣列精準控制動作存取權限，支援角色型存取控制 (RBAC) 基礎整合。

關鍵配置參數

角色識別符號

• ? — **游客** (未登入用戶)
• @ — **已登入用戶** (通過 Yii::$app->user->identity 識別)
• 角色名稱 — RBAC 角色 (如 admin, editor)，需配合 Yii::$app->user->can()

實戰範例：控制器行為配置

namespace app\controllers;

use yii\filters\AccessControl;
use yii\filters\VerbFilter;
use yii\web\Controller;

class SiteController extends Controller {
    public function behaviors() {
        return [
            'access' => [
                'class' => AccessControl::className(),
                // 策略：除了 login、signup 以外的所有動作都需登入
                'except' => ['login', 'signup'],
                'rules' => [
                    // 規則 1：允許游客存取 login、signup
                    [
                        'actions' => ['login', 'signup'],
                        'allow'   => true,
                        'roles'   => ['?'],
                    ],
                    // 規則 2：允許已登入用戶存取其他所有 (except 已排除 login/signup)
                    [
                        'allow' => true,
                        'roles' => ['@'],
                    ],
                ],
            ],
            'verbs' => [
                'class' => VerbFilter::className(),
                'actions' => [
                    'logout' => ['post'],  // 強制 POST 登出
                ],
            ],
        ];
    }

    public function actionLogin() { /* ... */ }
    public function actionSignup() { /* ... */ }
    public function actionProfile() { /* 需登入 */ }
    public function actionSettings() { /* 需登入 */ }
}

規則匹配邏輯圖解

請求 actionProfile
       │
       ▼
AccessControl behaviors()
       │
       ├── only/except 過濾 → 符合 (except 排除 login/signup)
       │
       ▼
遍歷 rules 陣列：
       │
       ├── Rule 1: actions=[login,signup] → 不匹配 → 繼續
       │
       ├── Rule 2: actions=未指定(全部), roles=[@] 
       │       │
       │       ├── 用戶已登入 (@ 符合) → allow=true → 允許存取 ✅
       │       └── 用戶未登入 (? 符合) → roles 不匹配 → 繼續
       │
       ▼
無規則匹配 → 預設拒絕 (denyCallback 或 403)

進階：角色型存取控制 (RBAC) 整合

'rules' => [
    // 管理員可存取所有後台
    [
        'allow' => true,
        'roles' => ['admin'],
        'matchCallback' => function ($rule, $action) {
            return Yii::$app->user->can('admin');  // RBAC 檢查
        },
    ],
    // 編輯可存取文章管理
    [
        'actions' => ['article-index', 'article-create', 'article-update'],
        'allow' => true,
        'roles' => ['editor'],
        'matchCallback' => fn() => Yii::$app->user->can('editor'),
    ],
    // 登入用戶可存取個人中心
    [
        'allow' => true,
        'roles' => ['@'],
    ],
]

自定義拒絕回應

'denyCallback' => function ($rule, $action) {
    if (Yii::$app->request->isAjax) {
        return Yii::$app->response->json(['code' => 403, 'msg' => '權限不足']);
    }
    // 重導向至登入頁，保留原 URL
    return Yii::$app->response->redirect(['site/login', 'redirect' => Yii::$app->request->url]);
},

常見誤區與避坑

總結

AccessControl 以 except + rules 組合實現「預設拒絕、例外允許」的安全策略。核心口訣：黑名單排除公開頁、白名單規則精準放行、角色符號分清游客與登入、拒絕回調友善回應。配合 RBAC 可構建企業級精細權限體系。