📚 PHP MVC 框架使用手册

📖 文档目录

🖥️ 环境要求 🚀 安装部署 📁 目录结构 🔀 路由系统 🎮 控制器 🗄️ 模型与数据库 🎨 视图模板 🔒 中间件 ⚡ 缓存机制 ✅ 参数验证 🛡️ 安全特性 ❓ 常见问题
📌 框架简介
这是一个 PHP 8.0+ MVC 框架，支持数据库读写分离、AI 友好路由、智能缓存、自动安全防护。

1 环境要求

依赖版本要求说明
PHP>= 8.0支持类型约束、空类型等特性
MySQL>= 5.7支持 JSON、数据类型等
PDO已启用PHP 数据库抽象层
PDO MySQL已启用MySQL 驱动

2 安装部署

方式一：图形化安装（推荐）

配置 Web 服务器，将根目录指向 public/
访问 http://localhost/install.php
按向导完成数据库配置和系统初始化
默认管理员账号：admin / admin123
✅ 安装完成
安装后会自动创建 .env 配置文件和 .installed 锁文件，系统启动时会自动检测安装状态。

方式二：手动安装

# 1. 安装依赖
composer install

# 2. 复制环境配置
cp .env.example .env

# 3. 修改 .env 中的数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=your_database
DB_USER=root
DB_PASS=your_password

# 4. 初始化数据库
mysql -u root -p < database/init.sql

# 5. 创建安装锁文件
touch .installed

Web 服务器配置

Apache (.htaccess)

RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?url=$1 [QSA,L]

Nginx

location / {
    try_files $uri $uri/ /index.php?url=$uri;
}

3 目录结构

mvc框架/ ├── app/ │ ├── Controllers/ # 控制器目录 │ │ └── UserController.php │ ├── Models/ # 模型目录 │ │ └── UserModel.php │ └── Views/ # 视图目录 │ └── user/ │ └── create.html ├── core/ # 框架核心 │ ├── App.php │ ├── Controller.php │ ├── Model.php │ └── ... ├── config/ # 配置文件 ├── public/ # 网站根目录 │ ├── index.php # 入口文件 │ └── install.php # 安装程序 ├── cache/ # 缓存目录 ├── logs/ # 日志目录 ├── .env # 环境配置 └── .installed # 安装锁文件

4 路由系统

自动路由

框架自动解析 URL：/控制器/方法/参数

URL调用
/user/indexUserController::index()
/user/show/1UserController::show(1)
/user/edit/5UserController::edit(5)

静态路由配置

编辑 config/routes.php：

<?php
// GET 路由
Route::get('/home', 'IndexController@index');
Route::get('/user/list', 'UserController@index');

// POST 路由
Route::post('/api/v1/users', 'UserController@store');

// RESTful 资源路由
Route::resource('/api/v1/users', 'UserController');

// 带参数的路由
Route::get('/user/profile/{id}', 'UserController@profile');

// 带中间件的路由
Route::get('/admin/dashboard', 'AdminController@dashboard')
    ->middleware(['AuthMiddleware', 'AdminMiddleware']);

RESTful 路由对照表

方法URL控制器方法说明
GET/usersindex()列表页
GET/users/createcreate()创建页
POST/usersstore()保存
GET/users/{id}show()详情页
GET/users/{id}/editedit()编辑页
PUT/users/{id}update()更新
DELETE/users/{id}destroy()删除

5 控制器

基础结构

<?php
class UserController extends Controller
{
    // 显示列表
    public function index(): void
    {
        $users = (new UserModel())->select()->get();
        $this->view('user/index', ['users' => $users]);
    }

    // 创建页面
    public function create(): void
    {
        $this->view('user/create', [
            'csrfToken' => $this->csrfToken()
        ]);
    }

    // 保存数据
    public function store(): void
    {
        // 验证 CSRF Token
        if (!$this->verifyCsrf($this->post('_token'))) {
            $this->json(['code' => 403, 'msg' => 'CSRF 验证失败'], 403);
            return;
        }

        // 验证参数
        $validator = new Validator();
        $data = $validator->validate($_POST, [
            'name'  => 'required|min:2|max:50',
            'email' => 'email',
        ]);

        if ($validator->hasErrors()) {
            $this->json(['code' => 422, 'msg' => '参数错误', 'errors' => $validator->getErrors()], 422);
            return;
        }

        // 保存数据
        $id = (new UserModel())->create($data);
        $this->redirect('/user/show/' . $id);
    }
}

控制器常用方法

方法说明
$this->view($view, $data)渲染视图
$this->json($data, $code)返回 JSON
$this->post($key, $default)获取 POST 数据（自动过滤 XSS）
$this->get($key, $default)获取 GET 参数（自动过滤 XSS）
$this->redirect($url)页面跳转
$this->csrfToken()生成 CSRF Token
$this->verifyCsrf($token)验证 CSRF Token

6 模型与数据库

基础模型

<?php
class UserModel extends Model
{
    protected string $table = 'users';
}

基础操作

$model = new UserModel();

// 查询单条（自动使用从库）
$user = $model->find(1);

// 查询所有
$users = $model->select()->get();

// 条件查询
$users = $model->select()
    ->where('status', '=', 1)
    ->where('name', 'like', '%张%')
    ->orderBy('created_at', 'desc')
    ->limit(10)
    ->get();

// 创建数据（自动使用主库）
$id = $model->create([
    'name'  => '张三',
    'email' => 'zhangsan@example.com'
]);

// 更新数据
$model->update(1, ['name' => '李四']);

// 删除数据
$model->delete(1);

// 统计数量
$count = $model->count();

// 分页查询
$page = $model->paginate(2, 15);
// 返回: ['data' => [], 'total' => 100, 'page' => 2, 'per_page' => 15, 'last_page' => 7]
✅ 读写分离
模型自动处理读写分离：查询使用从库（提升性能），写入使用主库（保证一致性）。从库故障时自动降级到主库。

QueryBuilder 链式查询

$model = new UserModel();

// 高级查询示例
$users = $model->select(['id', 'name', 'email'])
    ->where('status', '=', 1)
    ->whereIn('id', [1, 2, 3])
    ->whereBetween('age', 18, 30)
    ->leftJoin('departments', 'users.dept_id', '=', 'departments.id')
    ->orderBy('created_at', 'desc')
    ->groupBy('department')
    ->limit(10)
    ->get();

7 视图模板

视图文件使用 .html 格式，在控制器中调用：

$this->view('user/profile', ['user' => $user]);

视图示例

app/Views/user/profile.html

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title><?= htmlspecialchars($title, ENT_QUOTES, 'UTF-8') ?></title>
</head>
<body>
    <h1><?= htmlspecialchars($user['name'], ENT_QUOTES, 'UTF-8') ?></h1>

    <!-- 循环输出 -->
    <ul>
        <?php foreach ($posts as $post): ?>
            <li><?= htmlspecialchars($post['title'], ENT_QUOTES, 'UTF-8') ?></li>
        <?php endforeach; ?>
    </ul>

    <!-- 表单（带 CSRF Token）-->
    <form method="POST" action="/api/v1/users">
        <input type="hidden" name="_token" value="<?= $csrfToken ?>">
        <input type="text" name="name" placeholder="用户名">
        <button type="submit">提交</button>
    </form>
</body>
</html>

8 中间件

创建中间件

<?php
class AuthMiddleware implements MiddlewareInterface
{
    public function handle(callable $next): void
    {
        // 检查登录状态
        if (!isset($_SESSION['user_id'])) {
            header('Location: /login');
            exit;
        }

        $next();  // 继续执行后续逻辑
    }
}

使用中间件

// 单个中间件
Route::get('/admin/dashboard', 'AdminController@dashboard')
    ->middleware(AuthMiddleware::class);

// 多个中间件
Route::get('/admin/settings', 'AdminController@settings')
    ->middleware([AuthMiddleware::class, AdminMiddleware::class]);

9 缓存机制

文件缓存

$cache = new Cache();

// 设置缓存（默认 3600 秒）
$cache->set('user_1', ['name' => '张三'], 3600);

// 获取缓存
$user = $cache->get('user_1');
$user = $cache->get('user_999', ['name' => '游客']);  // 默认值

// 判断缓存是否存在
if ($cache->has('user_1')) { /* ... */ }

// 删除缓存
$cache->delete('user_1');

// 清空所有缓存
$cache->clear();

// 缓存不存在时自动回源
$user = $cache->remember('user_1', 3600, function () {
    return (new UserModel())->find(1);
});

Redis 缓存

配置 .env
CACHE_DRIVER=redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

10 参数验证

$validator = new Validator();

// 定义验证规则
$rules = [
    'username' => 'required|min:3|max:20',
    'email'    => 'required|email',
    'age'      => 'integer|min:18|max:100',
    'password' => 'required|min:6|confirmed',
];

// 执行验证
$data = $validator->validate($_POST, $rules);

// 检查错误
if ($validator->hasErrors()) {
    $errors = $validator->getErrors();
    $firstError = $validator->getFirstError();
    $this->json(['code' => 422, 'msg' => '参数错误', 'errors' => $errors], 422);
}

// 获取干净的数据
$cleanData = $validator->getData();

支持的验证规则

规则说明示例
required必填-
email邮箱格式-
integer整数-
min最小值/长度min:3
max最大值/长度max:50
between范围between:1,100
in枚举值in:1,2,3
regex正则表达式regex:/^\d+$/
confirmed确认字段自动验证 _confirmation

11 安全特性

功能说明状态
HTTPS 强制生产环境自动跳转 HTTPS已启用
CSRF 防护Token 验证防止跨站请求已启用
XSS 防护自动转义用户输入已启用
SQL 注入预处理语句防护已启用
读写分离主从库自动切换已启用

12 配置文件

.env 环境变量

# 应用配置
APP_ENV=production
APP_DEBUG=false
APP_URL=http://localhost

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=mvc_framework
DB_USER=root
DB_PASS=

# 缓存配置
CACHE_DRIVER=file

# Redis（可选）
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

数据库配置 (config/database.php)

<?php
return [
    'default' => 'mysql',

    'connections' => [
        'mysql' => [
            'host'     => env('DB_HOST', 'localhost'),
            'port'     => env('DB_PORT', '3306'),
            'database' => env('DB_NAME', 'mvc_framework'),
            'username' => env('DB_USER', 'root'),
            'password' => env('DB_PASS', ''),
            'charset'  => 'utf8mb4',

            // 从库配置（读写分离）
            'slave' => [
                'host'     => '192.168.1.101',
                'port'     => '3306',
                'username' => 'slave_user',
                'password' => 'slave_pass',
            ],
        ],
    ],
];

13 常见问题

Q: 如何获取当前登录用户？

$user = $_SESSION['user'] ?? null;

Q: 如何处理分页？

// 控制器
$page = isset($_GET['page']) ? (int)$_GET['page'] : 1;
$result = (new UserModel())->paginate($page, 15);

// 视图分页
<?php for ($i = 1; $i <= $result['last_page']; $i++): ?>
    <a href="?page=<?= $i ?>"><?= $i ?></a>
<?php endfor; ?>

Q: 如何记录日志？

// 异常自动记录到 logs/error-YYYY-MM-DD.log

// 手动记录
$logFile = ROOT . '/logs/app-' . date('Y-m-d') . '.log';
$logMsg = sprintf("[%s] INFO: 用户 %d 登录\n", date('Y-m-d H:i:s'), $userId);
file_put_contents($logFile, $logMsg, FILE_APPEND);
📝 文档版本
最后更新：2026年4月
框架版本：1.0.0
如有问题请联系技术支持。