PHPackages xiaououo/xiaophp - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. xiaououo/xiaophp ActiveProject xiaououo/xiaophp ================ 基于 PHP 的轻量级 MVC 框架，适合小型项目快速开发 V2.1.1(1mo ago)12Apache-2.0PHP Since Jul 15Pushed 1w agoCompare [ Source](https://github.com/xiaououo/XiaoPHP)[ Packagist](https://packagist.org/packages/xiaououo/xiaophp)[ RSS](/packages/xiaououo-xiaophp/feed)WikiDiscussions main Synced 1w ago READMEChangelog (4)DependenciesVersions (4)Used By (0) XiaoPHP V2.1.2 全面开发文档 ===================== [](#xiaophp-v212-全面开发文档) > **框架名称**：XiaoPHP（小新PHP） **当前版本**：V2.1.2 **作者**：小新（） **开源协议**：Apache-2.0 **官方主页**：**文档生成日期**：2026-08-18 **文档类型**：深度技术分析 + 开发指南 + 架构评估 --- 目录 -- [](#目录) - [第一部分 框架概述](#%E7%AC%AC%E4%B8%80%E9%83%A8%E5%88%86-%E6%A1%86%E6%9E%B6%E6%A6%82%E8%BF%B0) - [第二部分 架构设计深度解析](#%E7%AC%AC%E4%BA%8C%E9%83%A8%E5%88%86-%E6%9E%B6%E6%9E%84%E8%AE%BE%E8%AE%A1%E6%B7%B1%E5%BA%A6%E8%A7%A3%E6%9E%90) - [第三部分 安装与部署](#%E7%AC%AC%E4%B8%89%E9%83%A8%E5%88%86-%E5%AE%89%E8%A3%85%E4%B8%8E%E9%83%A8%E7%BD%B2) - [第四部分 配置系统详解](#%E7%AC%AC%E5%9B%9B%E9%83%A8%E5%88%86-%E9%85%8D%E7%BD%AE%E7%B3%BB%E7%BB%9F%E8%AF%A6%E8%A7%A3) - [第五部分 路由系统](#%E7%AC%AC%E4%BA%94%E9%83%A8%E5%88%86-%E8%B7%AF%E7%94%B1%E7%B3%BB%E7%BB%9F) - [第六部分 控制器开发](#%E7%AC%AC%E5%85%AD%E9%83%A8%E5%88%86-%E6%8E%A7%E5%88%B6%E5%99%A8%E5%BC%80%E5%8F%91) - [第七部分 视图模板引擎](#%E7%AC%AC%E4%B8%83%E9%83%A8%E5%88%86-%E8%A7%86%E5%9B%BE%E6%A8%A1%E6%9D%BF%E5%BC%95%E6%93%8E) - [第八部分 模型与数据库 ORM](#%E7%AC%AC%E5%85%AB%E9%83%A8%E5%88%86-%E6%A8%A1%E5%9E%8B%E4%B8%8E%E6%95%B0%E6%8D%AE%E5%BA%93-orm) - [第九部分 中间件与 Token 认证](#%E7%AC%AC%E4%B9%9D%E9%83%A8%E5%88%86-%E4%B8%AD%E9%97%B4%E4%BB%B6%E4%B8%8E-token-%E8%AE%A4%E8%AF%81) - [第十部分 用户登录认证 Auth](#%E7%AC%AC%E5%8D%81%E9%83%A8%E5%88%86-%E7%94%A8%E6%88%B7%E7%99%BB%E5%BD%95%E8%AE%A4%E8%AF%81-auth) - [第十一部分 依赖注入容器](#%E7%AC%AC%E5%8D%81%E4%B8%80%E9%83%A8%E5%88%86-%E4%BE%9D%E8%B5%96%E6%B3%A8%E5%85%A5%E5%AE%B9%E5%99%A8) - [第十二部分 缓存系统](#%E7%AC%AC%E5%8D%81%E4%BA%8C%E9%83%A8%E5%88%86-%E7%BC%93%E5%AD%98%E7%B3%BB%E7%BB%9F) - [第十三部分 日志系统](#%E7%AC%AC%E5%8D%81%E4%B8%89%E9%83%A8%E5%88%86-%E6%97%A5%E5%BF%97%E7%B3%BB%E7%BB%9F) - [第十四部分 文件管理](#%E7%AC%AC%E5%8D%81%E5%9B%9B%E9%83%A8%E5%88%86-%E6%96%87%E4%BB%B6%E7%AE%A1%E7%90%86) - [第十五部分 工具类大全](#%E7%AC%AC%E5%8D%81%E4%BA%94%E9%83%A8%E5%88%86-%E5%B7%A5%E5%85%B7%E7%B1%BB%E5%A4%A7%E5%85%A8) - [第十六部分 加密工具](#%E7%AC%AC%E5%8D%81%E5%85%AD%E9%83%A8%E5%88%86-%E5%8A%A0%E5%AF%86%E5%B7%A5%E5%85%B7) - [第十七部分 错误处理与调试](#%E7%AC%AC%E5%8D%81%E4%B8%83%E9%83%A8%E5%88%86-%E9%94%99%E8%AF%AF%E5%A4%84%E7%90%86%E4%B8%8E%E8%B0%83%E8%AF%95) - [第十八部分 多应用管理与 CLI](#%E7%AC%AC%E5%8D%81%E5%85%AB%E9%83%A8%E5%88%86-%E5%A4%9A%E5%BA%94%E7%94%A8%E7%AE%A1%E7%90%86%E4%B8%8E-cli) - [第十九部分 阿里云 DNS 集成](#%E7%AC%AC%E5%8D%81%E4%B9%9D%E9%83%A8%E5%88%86-%E9%98%BF%E9%87%8C%E4%BA%91-dns-%E9%9B%86%E6%88%90) - [第二十部分 安全指南](#%E7%AC%AC%E4%BA%8C%E5%8D%81%E9%83%A8%E5%88%86-%E5%AE%89%E5%85%A8%E6%8C%87%E5%8D%97) - [第二十一部分 最佳实践与代码规范](#%E7%AC%AC%E4%BA%8C%E5%8D%81%E4%B8%80%E9%83%A8%E5%88%86-%E6%9C%80%E4%BD%B3%E5%AE%9E%E8%B7%B5%E4%B8%8E%E4%BB%A3%E7%A0%81%E8%A7%84%E8%8C%83) - [第二十二部分 框架深度评估](#%E7%AC%AC%E4%BA%8C%E5%8D%81%E4%BA%8C%E9%83%A8%E5%88%86-%E6%A1%86%E6%9E%B6%E6%B7%B1%E5%BA%A6%E8%AF%84%E4%BC%B0) - [第二十三部分 常见问题 FAQ](#%E7%AC%AC%E4%BA%8C%E5%8D%81%E4%B8%89%E9%83%A8%E5%88%86-%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98-faq) - [附录 A 完整 API 速查表](#%E9%99%84%E5%BD%95-a-%E5%AE%8C%E6%95%B4-api-%E9%80%9F%E6%9F%A5%E8%A1%A8) - [附录 B 核心类源码索引](#%E9%99%84%E5%BD%95-b-%E6%A0%B8%E5%BF%83%E7%B1%BB%E6%BA%90%E7%A0%81%E7%B4%A2%E5%BC%95) --- 第一部分 框架概述 --------- [](#第一部分-框架概述) ### 1.1 框架定位 [](#11-框架定位) XiaoPHP 是一款**轻量级、零依赖、多应用架构**的 PHP MVC 框架，专为小型项目和快速开发设计。框架核心代码精简，不依赖 Composer 第三方包，所有功能均为原生实现。 **核心特性**： 特性说明零依赖`composer.json` 的 `require` 为空，纯原生 PHP 实现多应用支持 `App/{AppName}` 多应用隔离，每个应用独立 MVC 结构双路由自定义路由 + 自动路由（`/app/controller/method`）双认证Token 中间件认证 + Session 后台登录认证DI 容器支持自动装配、单例、循环依赖检测模板引擎自研编译型模板引擎，支持继承、包含、循环、条件查询构造器链式调用 PDO 查询构造器，防 SQL 注入文件缓存基于文件的轻量缓存，可选 Redis 后端安全防护XSS 自动转义、CSRF 双 Token、SQL 预编译、上传扫描### 1.2 环境要求 [](#12-环境要求) 组件最低版本说明PHP7.4+推荐 PHP 8.0+MySQL5.6+需要 PDO 扩展Web ServerApache / Nginx / PHP Built-in任一即可Redis可选需要 `redis` PHP 扩展cURL推荐Wget/Json 工具需要OpenSSL推荐AES/RSA 加密需要fileinfo推荐文件上传 MIME 检测需要### 1.3 版本信息 [](#13-版本信息) - **版本号**：V2.1.2 - **核心代码量**：约 30+ PHP 文件，约 5000+ 行 - **发布日期**：2026-07-24（基于日志和文件时间戳） - **PHP 严格模式**：入口文件使用 `declare(strict_types=1)` --- 第二部分 架构设计深度解析 ------------- [](#第二部分-架构设计深度解析) ### 2.1 整体架构图 [](#21-整体架构图) ``` ┌─────────────────────────┐ │ HTTP Request │ └────────────┬────────────┘ │ ┌────────────▼────────────┐ │ Public/index.php │ 入口：ob_start、Session、常量定义 └────────────┬────────────┘ │ ┌────────────▼────────────┐ │ XiaoPHP/console.php │ SPL 自动加载器 + 系统文件加载 └────────────┬────────────┘ │ ┌──────────────────────┼──────────────────────┐ │ │ │ ┌──────────▼─────────┐ ┌────────▼────────┐ ┌────────────▼───────────┐ │ ServiceProvider │ │ start.php │ │ App/Loading.php │ │ 注册核心服务到容器 │ │ 错误/异常处理 │ │ 多应用文件自动加载 │ └────────────────────┘ └────────┬────────┘ └────────────────────────┘ │ ┌──────────▼──────────┐ │ Routing.php │ 路由分发引擎 └──────────┬──────────┘ │ ┌──────────▼──────────┐ │ Middleware::check()│ Token 认证中间件 └──────────┬──────────┘ │ ┌────────────────────┼────────────────────┐ │ │ │ ┌──────────▼─────────┐ ┌───────▼───────┐ ┌──────────▼─────────┐ │ 自定义路由匹配 │ │ 自动路由解析 │ │ 白名单跳过认证 │ │ Route::find() │ │ /app/ctrl/mtd │ │ Whitelist::check() │ └──────────┬─────────┘ └───────┬───────┘ └────────────────────┘ │ │ └──────────┬─────────┘ │ ┌──────────▼──────────┐ │ 控制器实例化(DI) │ Container::make() 自动装配 └──────────┬──────────┘ │ ┌──────────▼──────────┐ │ 控制器方法执行 │ │ return / echo │ └──────────┬──────────┘ │ ┌──────────▼──────────┐ │ Logs::logs() │ 记录请求日志 └─────────────────────┘ ``` ### 2.2 请求生命周期 [](#22-请求生命周期) 1. **入口阶段**（`Public/index.php`） - 开启输出缓冲 `ob_start()` - 检测 Session 存储目录可写性，不可写则回退到 `runtime/sessions` - 启动 Session - 定义常量 `SYS_PATH`（框架核心目录）、`SYS_ROOT`（Public 目录） - 加载 `XiaoPHP/console.php` 2. **加载阶段**（`XiaoPHP/console.php`） - 注册 SPL 自动加载器（按命名空间映射文件路径） - 递归加载 `XiaoPHP/System/` 下所有 PHP 文件 - 加载全局配置 `Config/*.php` - 加载白名单、错误处理、中间件、调试、安装器、导入器 - 加载 `App/Loading.php`（多应用文件自动加载） - 加载自定义路由 `Route/Route.php` - 注册核心服务到 DI 容器（`ServiceProvider::register()`） - 加载路由分发引擎 `Routing.php` 3. **错误处理注册**（`XiaoPHP/start.php`） - `register_shutdown_function`：捕获致命错误（E\_ERROR、E\_PARSE 等） - `set_error_handler`：将错误转为 `ErrorException` 异常 - `set_exception_handler`：统一异常处理，调用 `displayDebugInfo()` 4. **路由分发阶段**（`XiaoPHP/Routing.php`） - 从 DI 容器获取 `Middleware` 实例，执行 `check()` 认证 - 解析请求路径，提取 App/Controller/Method 三段 - 优先匹配自定义路由（`Route::find()`） - 未匹配则走自动路由 - 通过 `Helper::loadSiblingControllers()` 先加载基类（\*Base.php 优先） - 通过 DI 容器实例化控制器（支持构造函数自动注入） - 不区分大小写查找方法并执行 - 记录成功/错误日志 5. **响应阶段** - 控制器 `return` 的字符串被 `echo` 输出 - 或控制器中直接 `echo` / `Json::encode()` / `Error()` - `exit(0)` 终止执行 ### 2.3 自动加载机制 [](#23-自动加载机制) 框架实现了**自定义 SPL 自动加载器**，不依赖 Composer 的 PSR-4 自动加载（虽然也支持 `vendor/autoload.php`）。 **命名空间到文件路径的映射规则**： 命名空间模式文件路径示例`XiaoPHP\System\*``XiaoPHP/{classPath}.php``XiaoPHP\System\Container` → `XiaoPHP/System/Container.php``XiaoPHP\System\Config\*``XiaoPHP/System/Tools/Config/{basename}.php``XiaoPHP\System\Config\Conf` → `XiaoPHP/System/Tools/Config/Conf.php``XiaoPHP\System\Tools\*``XiaoPHP/System/Tools/{basename}.php``XiaoPHP\System\Tools\App\RedisTools` → `XiaoPHP/System/Tools/RedisTools.php``App\*``App/{classPath}.php``App\Admin\Model\UserModel` → `App/Admin/Model/UserModel.php`> **注意**：自动加载器中配置类和工具类的映射使用了 `basename()`，这意味着这些类的子命名空间会被忽略，直接取类名。例如 `XiaoPHP\System\Tools\App\MysqlTools` 会映射到 `XiaoPHP/System/Tools/MysqlTools.php`，但实际文件在 `Tools/App/MysqlTools.php`。不过由于 `console.php` 中使用 `loadSystemFiles()` 递归加载了所有 System 下的 PHP 文件，这些类在自动加载触发前就已经被 `require_once` 了，所以不会有问题。 ### 2.4 多应用架构 [](#24-多应用架构) XiaoPHP 采用**多应用（Multi-App）架构**，每个应用是 `App/` 下的一个独立目录，拥有完整的 MVC 结构： ``` App/ ├── Index/ # 默认应用 │ ├── Controller/ # 控制器 │ ├── Model/ # 模型 │ ├── View/ # 视图 │ ├── Function/ # 业务函数 │ ├── Config/ # 应用配置 │ └── app.json # 应用开关 ├── Admin/ # 后台应用（示例） │ └── ... └── Loading.php # 应用加载器 ``` **应用加载机制**（`App/Loading.php`）： - 扫描 `App/` 下所有子目录 - 读取每个应用的 `app.json`，检查 `status` 字段 - `status: "on"` → 自动加载该应用下 `Config/`、`Function/`、`Model/` 目录的所有 PHP 文件 - `status: "off"` → 跳过该应用的所有文件加载 - `Controller/` 目录不预加载，由路由按需加载 ### 2.5 核心命名空间与类映射 [](#25-核心命名空间与类映射) 完全限定类名文件路径职责`XiaoPHP\System\Container``System/Tools/Function/Container.php`DI 容器`XiaoPHP\System\Helper``System/Tools/Function/Helper.php`辅助工具（不区分大小写查找）`XiaoPHP\System\Cache``System/Tools/Function/Cache.php`文件缓存`XiaoPHP\System\Logs``System/Tools/Function/Logs.php`日志记录`XiaoPHP\System\View``System/Tools/Function/view.php`视图模板引擎`XiaoPHP\System\Model``System/Tools/Function/Model.php`模型基类`XiaoPHP\System\Auth``System/Tools/Function/Auth.php`Session 登录认证`XiaoPHP\System\Validate``System/Tools/Function/Validate.php`数据验证`XiaoPHP\System\Json``System/Tools/Function/Json.php`JSON 工具`XiaoPHP\System\File``System/Tools/Function/File.php`文件上传管理`XiaoPHP\System\Wget``System/Tools/Function/Wget.php`HTTP 客户端`XiaoPHP\System\Ipaddr``System/Tools/Function/Ipaddr.php`IP 地址获取`XiaoPHP\System\Middleware``XiaoPHP/Middleware.php`Token 认证中间件`XiaoPHP\System\AesTool``System/Tools/encrypt/AesTools.php`AES 加密`XiaoPHP\System\RSATool``System/Tools/encrypt/RSATools.php`RSA 加密`XiaoPHP\System\Config\Conf``System/Tools/Config/Conf.php`配置读取`XiaoPHP\System\Config\Env``System/Tools/Config/Env.php`环境变量`XiaoPHP\System\Config\Route``System/Tools/Config/Route.php`路由注册`XiaoPHP\System\Config\Whitelist``System/Tools/Config/Whitelist.php`白名单管理`XiaoPHP\System\Config\ServiceProvider``System/Tools/Config/ServiceProvider.php`服务提供者`XiaoPHP\System\Tools\App\MysqlTools``System/Tools/App/MysqlTools.php`数据库查询构造器`XiaoPHP\System\Tools\App\RedisTools``System/Tools/App/RedisTools.php`Redis 操作封装`XiaoPHP\app\tools\AliyunDns``System/Tools/App/AliyunDns.php`阿里云 DNS API--- 第三部分 安装与部署 ---------- [](#第三部分-安装与部署) ### 3.1 获取框架 [](#31-获取框架) ``` # 解压框架包 unzip XiaoPHPV2.1.2.zip -d /var/www/xiaophp cd /var/www/xiaophp ``` ### 3.2 目录权限设置 [](#32-目录权限设置) ``` # 确保以下目录可写 chmod -R 755 Temp/ logs/ Resources/File/ chown -R www-data:www-data Temp/ logs/ Resources/File/ ``` ### 3.3 Nginx 配置 [](#33-nginx-配置) ``` server { listen 80; server_name your-domain.com; root /var/www/xiaophp/Public; index index.php; # 伪静态：所有请求转发到 index.php location / { try_files $uri $uri/ /index.php?$query_string; } # PHP 解析 location ~ \.php$ { fastcgi_pass 127.0.0.1:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } # 禁止访问敏感文件 location ~ /\.(env|git) { deny all; } } ``` ### 3.4 Apache 配置 [](#34-apache-配置) 确保启用 `mod_rewrite`，`Public/.htaccess` 已内置重写规则（当前版本 `.htaccess` 为空文件，需手动添加）： ``` RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^(.*)$ index.php/$1 [QSA,PT,L] ``` ### 3.5 PHP 内置服务器（开发用） [](#35-php-内置服务器开发用) ``` cd /var/www/xiaophp/Public php -S 0.0.0.0:8080 router.php ``` 访问 `http://localhost:8080/` 验证安装。 ### 3.6 环境变量配置 [](#36-环境变量配置) 编辑项目根目录的 `.env` 文件： ``` # MySQL 数据库 DB_HOST=127.0.0.1 DB_PORT=3306 DB_NAME=your_database DB_USER=your_username DB_PASSWORD=your_password # Redis（可选） REDIS_HOST=127.0.0.1 REDIS_PORT=6379 REDIS_PASSWORD= # 框架调试模式 DEBUG=true # 开发环境设为 true，生产环境设为 false ``` ### 3.7 部署验证清单 [](#37-部署验证清单) - Web 服务器文档根目录指向 `Public/` - `.env` 数据库配置正确 - `Temp/`、`logs/`、`Resources/File/` 目录可写 - 访问 `/` 显示欢迎页面 - 生产环境 `DEBUG=false` - `.env` 文件不可通过 Web 访问 --- 第四部分 配置系统详解 ----------- [](#第四部分-配置系统详解) ### 4.1 配置加载流程 [](#41-配置加载流程) ``` .env 文件 → Env::Load() 解析 → Config/*.php 读取 Env 值 → Conf::get() 缓存返回 ``` ### 4.2 环境变量类 Env [](#42-环境变量类-env) **命名空间**：`XiaoPHP\System\Config\Env` **核心方法**： ``` // 加载 .env 文件并读取指定 key Env::load(null, "DEBUG"); // 加载 .env，读取 DEBUG Env::load(".local", "DB_HOST"); // 加载 .env.local，读取 DB_HOST // 读取已加载的环境变量（带默认值） Env::get("DB_HOST", "localhost"); ``` **支持的值类型自动转换**： - `true` / `false` → 布尔值 - `null` → null - 纯数字 → int / float - 带引号的值 → 去除引号 **多环境支持**：通过 `Env::load(".prod")` 加载 `.env.prod` 文件。 ### 4.3 配置读取类 Conf [](#43-配置读取类-conf) **命名空间**：`XiaoPHP\System\Config\Conf` ``` // 读取配置（首次从文件加载，后续从缓存返回） $appConfig = Conf::get("App"); // 加载 Config/App.php $mysqlConfig = Conf::get("Mysql"); // 加载 Config/Mysql.php // 清除配置缓存 Conf::clearCache("App"); // 清除指定配置 Conf::clearCache(); // 清除所有 ``` 配置文件返回数组，`Conf::get()` 返回 `?array`。 ### 4.4 全局配置文件一览 [](#44-全局配置文件一览) #### 4.4.1 应用配置 `Config/App.php` [](#441-应用配置-configappphp) ``` return [ "debug" => Env::Load(null, "DEBUG") ?? 'false', // 调试模式 "error" => 'html', // 错误响应格式: html | json ]; ``` 配置项类型说明`debug`string`'true'` 显示详细调试页，`'false'` 显示通用错误页`error`string`'html'` 渲染错误页面模板，`'json'` 返回 JSON#### 4.4.2 数据库配置 `Config/Mysql.php` [](#442-数据库配置-configmysqlphp) ``` return [ "host" => Env::Load(null, "DB_HOST") ?? 'localhost', "port" => Env::Load(null, "DB_PORT") ?? '3306', "user" => Env::Load(null, "DB_USER") ?? 'root', "password" => Env::Load(null, "DB_PASSWORD") ?? '123456', "dbname" => Env::Load(null, "DB_NAME") ?? 'xiaophp', ]; ``` #### 4.4.3 Redis 配置 `Config/Redis.php` [](#443-redis-配置-configredisphp) ``` return [ "host" => Env::Load(null, "REDIS_HOST") ?? '127.0.0.1', "port" => Env::Load(null, "REDIS_PORT") ?? '6379', "password" => Env::Load(null, "REDIS_PASSWORD") ?? '', ]; ``` #### 4.4.4 缓存配置 `Config/Cache.php` [](#444-缓存配置-configcachephp) ``` return [ "dir" => __DIR__ . '/../Temp/Cache/', // 缓存文件目录 "expire" => '3600', // 默认过期时间（秒） ]; ``` #### 4.4.5 中间件配置 `Config/Middleware.php` [](#445-中间件配置-configmiddlewarephp) ``` return [ "storage" => 'cache', // 存储方式: cache | redis "token_key" => 'token', // Token 参数名 "auth_mode" => 'bearer,post,cookie', // 认证方式（逗号分隔，按优先级） "cookie_name" => 'auth_token', // Cookie 名称 "cookie_expire" => '7200', // 默认过期时间（秒） ]; ``` #### 4.4.6 日志配置 `Config/Logs.php` [](#446-日志配置-configlogsphp) ``` return [ "success" => 'true', // 记录成功请求日志 "error" => 'true', // 记录错误请求日志 ]; ``` #### 4.4.7 阿里云 DNS 配置 `Config/AliyunDns.php` [](#447-阿里云-dns-配置-configaliyundnsphp) ``` return [ "accessKeyId" => '', // 阿里云 AccessKey ID "accessKeySecret" => '', // 阿里云 AccessKey Secret ]; ``` ### 4.5 应用级配置 [](#45-应用级配置) 每个应用可以有自己的 `Config/` 目录，其中的 PHP 文件会在应用加载时被自动 `require_once`。应用级配置的读取方式由开发者自行定义。 --- 第五部分 路由系统 --------- [](#第五部分-路由系统) ### 5.1 双路由机制 [](#51-双路由机制) XiaoPHP 支持**两种路由模式**，优先级为：自定义路由 > 自动路由。 #### 5.1.1 自定义路由 [](#511-自定义路由) 在 `Route/Route.php` 中注册： ``` use XiaoPHP\System\Config\Route; // 语法：Route::add(HTTP方法, URL路径, 控制器类名, 应用名, [方法名]) Route::add("GET", "/", "Index", "Index"); Route::add("GET", "/about", "About", "Index"); Route::add("POST", "/api/login", "Login", "Admin"); Route::add("PUT", "/api/user/1", "User", "Admin"); Route::add("DELETE", "/api/user/1", "User", "Admin"); // 指定方法名（第五个参数，默认 Main） Route::add("GET", "/user/list", "User", "Admin", "List"); ``` **内部存储格式**： ``` self::$routes[$url][$method] = "控制器类名/方法名:App/应用名/Controller" ``` **匹配返回格式**： ``` "GET:Index/Main:App/Index/Controller" ``` #### 5.1.2 自动路由 [](#512-自动路由) URL 格式：`/{AppName}/{ControllerName}/{MethodName}` ``` http://localhost/Index/Index/Main ↑App ↑控制器 ↑方法 http://localhost/Admin/User/List http://localhost/Index/Index → 省略 Method，默认 Main http://localhost/Index/Index/ → 尾部斜杠自动处理 ``` **路由解析规则**： 1. 去除 URL 首尾斜杠，去除查询字符串 2. 转为小写（不区分大小写） 3. 按 `/` 分割为三段：app、controller、method 4. 每段经过 `preg_replace("/[^a-zA-Z0-9_-]/", "", $seg)` 过滤，只保留字母数字下划线连字符 5. method 为空时默认 `Main` ### 5.2 路由分发引擎详解 [](#52-路由分发引擎详解) **文件**：`XiaoPHP/Routing.php` **执行流程**： 1. **获取容器实例**：`Container::getInstance()` 2. **中间件检查**：`$middleware->check()`（白名单路径自动跳过） 3. **解析路径**：从 `$_SERVER['REQUEST_URI']` 提取路径 4. **自定义路由匹配**：`Route::find($path, $method)` - 匹配成功 → 解析路由字符串 → 验证请求方法 → 加载控制器 → 执行 - 匹配失败 → 走自动路由 5. **自动路由**： - 验证 app 目录存在（`Helper::findDirCaseInsensitive`） - 验证 controller 文件存在（`Helper::findFileCaseInsensitive`） - 加载兄弟控制器文件（基类优先） - 通过 DI 容器实例化控制器 - 不区分大小写查找方法并执行 6. **记录日志**：成功 `logs(0, 200)`，失败 `logs(1, 状态码)` ### 5.3 不区分大小写机制 [](#53-不区分大小写机制) 框架通过 `Helper` 类实现了**文件、目录、方法名的不区分大小写查找**： ``` // 不区分大小写查找文件 Helper::findFileCaseInsensitive("/App/Index/Controller", "index.php"); // → 返回 /App/Index/Controller/Index.php // 不区分大小写查找目录 Helper::findDirCaseInsensitive("/App", "index"); // → 返回 /App/Index // 不区分大小写查找方法 Helper::findMethodCaseInsensitive($controllerInstance, "main"); // → 返回 "Main" ``` 这意味着 URL 中的 `/index/index/main` 和 `/Index/Index/Main` 效果相同。 ### 5.4 兄弟控制器加载机制 [](#54-兄弟控制器加载机制) `Helper::loadSiblingControllers()` 会在加载目标控制器前，先加载同目录下的所有其他 PHP 文件，并确保 `*Base.php` 命名的基类优先加载： ``` // App/Admin/Controller/ 目录下有： // AdminBase.php → 基类，优先加载 // User.php → 目标控制器 // Auth.php → 其他控制器 // 加载 User.php 时，自动先加载 AdminBase.php，再加载 Auth.php ``` 这解决了控制器继承基类时的加载顺序问题。 ### 5.5 请求方法验证 [](#55-请求方法验证) 自定义路由会验证 HTTP 请求方法是否匹配： ``` // 路由注册为 POST，但实际请求为 GET // → 返回 405 Method Not Allowed Error(405, "请求方法不允许"); ``` ### 5.6 路由配置最佳实践 [](#56-路由配置最佳实践) ``` // Route/Route.php use XiaoPHP\System\Config\Route; // 首页 Route::add("GET", "/", "Index", "Index"); // API 路由（RESTful 风格） Route::add("GET", "/api/users", "User", "Api", "List"); Route::add("POST", "/api/users", "User", "Api", "Create"); Route::add("GET", "/api/users/{id}", "User", "Api", "Show"); // 注意：当前版本不支持参数捕获 // 后台路由 Route::add("GET", "/admin", "Dashboard", "Admin"); Route::add("POST", "/admin/login", "Auth", "Admin", "DoLogin"); ``` > **注意**：当前版本的自定义路由**不支持 URL 参数捕获**（如 `/user/{id}`），参数需要通过 `$_GET` 或 `$_POST` 获取。 --- 第六部分 控制器开发 ---------- [](#第六部分-控制器开发) ### 6.1 控制器基本结构 [](#61-控制器基本结构) 控制器文件放在 `App/{AppName}/Controller/` 目录下，类名与文件名一致（不区分大小写）。 ```