ThinkPHP 框架入门教程 — 国产PHP框架首选

前置要求：PHP基础、MySQL基础

学习时长：约2-3天（每天4小时）

ThinkPHP版本：8.0+

适用场景：国内中小企业项目、CMS、后台管理系统

一、ThinkPHP 是什么？

ThinkPHP 是中国最流行的PHP框架，以中文文档完善、学习曲线平缓著称，是国内PHP开发的首选框架之一。

二、安装与配置

2.1 安装

# 使用Composer创建项目
composer create-project topthink/think myproject

# 进入项目
cd myproject

# 启动开发服务器
php think run
# 访问 http://localhost:8000

2.2 项目结构

myproject/
├── app/                    # 应用目录
│   ├── controller/         # 控制器
│   ├── model/              # 模型
│   ├── middleware/          # 中间件
│   ├── validate/           # 验证器
│   └── common.php          # 公共函数
├── config/                 # 配置文件
│   ├── app.php             # 应用配置
│   ├── database.php        # 数据库配置
│   └── route.php           # 路由配置
├── route/                  # 路由定义
│   └── app.php
├── public/                 # 入口目录（Nginx根目录）
│   └── index.php           # 入口文件
├── runtime/                # 运行时缓存
├── vendor/                 # Composer依赖
├── think                   # 命令行工具
└── composer.json

2.3 配置文件

// config/database.php
return [
    'default' => 'mysql',
    'connections' => [
        'mysql' => [
            'type' => 'mysql',
            'hostname' => '127.0.0.1',
            'database' => 'mydb',
            'username' => 'root',
            'password' => 'your_password',
            'charset' => 'utf8mb4',
            'prefix' => 'tp_',
            'debug' => true,
        ],
    ],
];

// config/app.php
return [
    'app_host' => '',
    'app_debug' => true,
    'default_timezone' => 'Asia/Shanghai',
    'exception_tmpl' => app()->getThinkPath() . 'tpl/think_exception.tpl',
];

三、路由系统

// route/app.php
use think\facade\Route;

// ====================
// 基本路由
// ====================
Route::get('/', function () {
    return 'Hello, ThinkPHP!';
});

// ====================
// 路由参数
// ====================
Route::get('user/:id', function ($id) {
    return "用户ID: " . $id;
});

// 可选参数
Route::get('user/:name?', function ($name = 'Guest') {
    return "用户名: " . $name;
});

// 参数规则
Route::get('user/:id', 'user/read')->pattern(['id' => '\d+']);

// ====================
// 资源路由（RESTful）
// ====================
Route::resource('users', 'User');
// 自动生成：
// GET    /users          → index
// GET    /users/create   → create
// POST   /users          → store
// GET    /users/:id      → read
// GET    /users/:id/edit → edit
// PUT    /users/:id      → update
// DELETE /users/:id      → delete

// ====================
// 路由分组
// ====================
Route::group('api', function () {
    Route::get('users', 'api/User/index');
    Route::post('users', 'api/User/create');
    Route::get('users/:id', 'api/User/read');
    Route::put('users/:id', 'api/User/update');
    Route::delete('users/:id', 'api/User/delete');
})->middleware(['cors', 'auth']);

// ====================
// 命名路由
// ====================
Route::get('user/:id', 'user/read')->name('user.read');
// 生成URL：url('user.read', ['id' => 123])

四、控制器

<?php
// app/controller/User.php
namespace app\controller;

use app\model\User as UserModel;
use think\Request;
use think\response\Json;

class User
{
    // 获取列表
    public function index(Request $request): Json
    {
        $keyword = $request->get('keyword', '');
        $page = $request->get('page', 1);
        $size = $request->get('size', 10);
        
        $query = UserModel::order('id', 'desc');
        
        if ($keyword) {
            $query->where('username|email', 'like', "%{$keyword}%");
        }
        
        $list = $query->paginate([
            'page' => $page,
            'list_rows' => $size,
        ]);
        
        return json([
            'code' => 200,
            'message' => 'success',
            'data' => $list,
        ]);
    }

    // 获取详情
    public function read(int $id): Json
    {
        $user = UserModel::find($id);
        
        if (!$user) {
            return json(['code' => 404, 'message' => '用户不存在'], 404);
        }
        
        return json([
            'code' => 200,
            'data' => $user,
        ]);
    }

    // 创建
    public function create(Request $request): Json
    {
        $data = $request->post();
        
        // 验证
        $validate = new \app\validate\User();
        if (!$validate->check($data)) {
            return json([
                'code' => 422,
                'message' => '验证失败',
                'errors' => $validate->getError(),
            ], 422);
        }
        
        // 检查用户名是否已存在
        if (UserModel::where('username', $data['username'])->find()) {
            return json(['code' => 409, 'message' => '用户名已存在'], 409);
        }
        
        $user = UserModel::create([
            'username' => $data['username'],
            'email' => $data['email'],
            'password' => password_hash($data['password'], PASSWORD_DEFAULT),
        ]);
        
        return json([
            'code' => 201,
            'message' => '创建成功',
            'data' => $user,
        ], 201);
    }

    // 更新
    public function update(int $id, Request $request): Json
    {
        $user = UserModel::find($id);
        
        if (!$user) {
            return json(['code' => 404, 'message' => '用户不存在'], 404);
        }
        
        $data = $request->put();
        $user->save($data);
        
        return json([
            'code' => 200,
            'message' => '更新成功',
            'data' => $user,
        ]);
    }

    // 删除
    public function delete(int $id): Json
    {
        $user = UserModel::find($id);
        
        if (!$user) {
            return json(['code' => 404, 'message' => '用户不存在'], 404);
        }
        
        $user->delete();
        
        return json([
            'code' => 200,
            'message' => '删除成功',
        ]);
    }
}

五、模型（Model）

<?php
// app/model/User.php
namespace app\model;

use think\Model;

class User extends Model
{
    // 表名（默认自动推断）
    protected $name = 'user';
    
    // 主键
    protected $pk = 'id';
    
    // 自动时间戳
    protected $autoWriteTimestamp = true;
    
    // 允许写入的字段
    protected $insert = ['created_at'];
    protected $update = ['updated_at'];
    
    // 隐藏字段（序列化时）
    protected $hidden = ['password'];
    
    // 类型转换
    protected $type = [
        'is_active' => 'boolean',
        'created_at' => 'datetime',
    ];

    // ====================
    // 模型方法
    // ====================
    
    // 关联：用户有多个文章
    public function posts()
    {
        return $this->hasMany(Post::class, 'user_id');
    }
    
    // 关联：用户属于一个部门
    public function department()
    {
        return $this->belongsTo(Department::class, 'dept_id');
    }
    
    // 访问器
    public function getDisplayNameAttr($value, $data)
    {
        return $data['nickname'] ?: $data['username'];
    }
    
    // 修改器
    public function setPasswordAttr($value)
    {
        return password_hash($value, PASSWORD_DEFAULT);
    }
    
    // 搜索器
    public function searchKeywordAttr($query, $value)
    {
        $query->where('username|email', 'like', "%{$value}%");
    }
    
    // 作用域
    public function scopeActive($query)
    {
        $query->where('is_active', 1);
    }
    
    public function scopeRecent($query, $days = 7)
    {
        $query->whereTime('created_at', '>=', date('Y-m-d', strtotime("-{$days} days")));
    }
}

// ====================
// 使用示例
// ====================

// 创建
$user = User::create([
    'username' => '张三',
    'email' => 'zhangsan@example.com',
    'password' => '123456',
]);

// 查询
$users = User::active()->recent(30)->paginate(10);
$user = User::find(1);
$user = User::where('username', '张三')->find();

// 搜索器
$users = User::withSearch(['keyword'], ['keyword' => '张'])->select();

// 更新
$user->username = '李四';
$user->save();

// 删除
$user->delete();

六、验证器

<?php
// app/validate/User.php
namespace app\validate;

use think\Validate;

class User extends Validate
{
    protected $rule = [
        'username' => 'require|alphaDash|length:3,50|unique:user',
        'email' => 'require|email|unique:user',
        'password' => 'require|length:6,100',
        'phone' => 'mobile',
    ];

    protected $message = [
        'username.require' => '用户名不能为空',
        'username.alphaDash' => '用户名只能包含字母、数字、下划线和破折号',
        'username.length' => '用户名长度必须在3-50之间',
        'username.unique' => '用户名已被使用',
        'email.require' => '邮箱不能为空',
        'email.email' => '邮箱格式不正确',
        'email.unique' => '邮箱已被使用',
        'password.require' => '密码不能为空',
        'password.length' => '密码长度必须在6-100之间',
        'phone.mobile' => '手机号格式不正确',
    ];
}

// 在控制器中使用
$validate = new \app\validate\User();
if (!$validate->check($data)) {
    return json(['errors' => $validate->getError()], 422);
}

七、中间件

<?php
// app/middleware/Auth.php
namespace app\middleware;

use think\Request;
use think\Response;

class Auth
{
    public function handle(Request $request, \Closure $next): Response
    {
        $token = $request->header('Authorization');
        
        if (!$token) {
            return json(['code' => 401, 'message' => '未登录'], 401);
        }
        
        // 验证token
        $userId = $this->verifyToken($token);
        if (!$userId) {
            return json(['code' => 401, 'message' => 'token无效'], 401);
        }
        
        // 设置用户信息
        $request->userId = $userId;
        
        return $next($request);
    }
    
    private function verifyToken(string $token): ?int
    {
        // JWT验证逻辑
        // ...
        return 1; // 示例
    }
}

// 注册中间件（app/middleware.php）
return [
    \think\middleware\AllowCrossDomain::class,  // 跨域
    \app\middleware\Auth::class,                 // 认证
];

// 路由中使用中间件
Route::group('api', function () {
    // ...
})->middleware(\app\middleware\Auth::class);

八、常见操作速查

# 创建控制器
php think make:controller User

# 创建模型
php think make:model User

# 创建验证器
php think make:validate User

# 创建中间件
php think make:middleware Auth

# 创建命令
php think make:command MyCommand

# 数据库迁移
php think migrate:create create_users_table
php think migrate:run

# 清除缓存
php think clear

# 查看路由列表
php think route:list

九、与 Laravel 对比

学习建议

1. 先看官方文档，ThinkPHP中文文档质量很高
2. 理解MVC架构，控制器、模型、视图各司其职
3. 掌握模型操作，数据库操作是核心
4. 学习验证器，输入验证是安全的基础
5. 做一个完整项目，如博客或后台管理系统

下一步学习

• Laravel 框架 — 更流行的企业级框架
• Vue.js 前端 — 前后端分离开发