Download the PHP package larkframe/template without Composer

LarkFrame 项目模板

基于 LarkFrame Core 框架的项目模板，开箱即用。

环境要求

• PHP >= 8.1
• ext-json, ext-pdo, ext-gd
• Redis（队列 /api/queue、Task 示例依赖；默认使用 phpredis 扩展，未安装时在 config/config.php 的 redis 配置中加 'client' => 'predis'）
• MySQL（/api/db 示例依赖）
• Composer

快速开始

默认监听 http://0.0.0.0:8080

首次启动时，框架会自动在项目根目录创建 .env 文件（包含 APP_NAME、TIME_ZONE、RUN_MODE），无需手动配置。

项目结构

框架文档

框架 larkframe/core 的完整组件文档随包分发（不在本模板内）：

• composer 安装态：vendor/larkframe/core/docs/*.md（16 个组件专题文档）
• 本地 path 仓库开发态：../core/docs/*.md
• AI 辅助编程入口：AGENTS.md（含框架文档索引与 API 速查）

核心功能示例

路由

路由定义在 config/route.php：

控制器

数据库

缓存

Redis

队列

队列任务类：

中间件

注册中间件：

工具集

视图

配置说明

环境变量 (.env)

.env 文件仅用于定义应用启动参数，框架首次启动时会自动创建（默认 RUN_MODE=prod）。它不会注入到 config() 配置系统中。

敏感配置（数据库密码、Redis 密码等）应通过 config/config.{env}.php 环境覆盖文件管理，而非 .env。

config/config.php 中 app.debug 默认 false（生产安全）。开发时将 .env 的 RUN_MODE 改为 dev，并创建 config/config.dev.php 覆盖 ['app' => ['debug' => true]] 即可开启堆栈详情。

多环境配置

注意（浅合并）：环境覆盖为顶层 array_merge——覆盖文件中的顶层键 （如 server）会整体替换主配置的对应键，必须携带完整子结构。 例如 config.dev.php 覆盖 server.socketName 时需同时带上 server.middleware， 否则全局中间件会被清空。

自定义类库配置

app/Library/Notify.php 对应 config/notify.php，配置自动加载到 $this->config：

运行模式

框架通过入口文件显式指定运行模式（App::run(LarkFrame\Consts::RUN_TYPE_*)）：

Server 模式（推荐）

常驻内存，事件驱动，高性能，支持多 Worker 进程。

Server 模式启动后监听 config.server.socketName 指定的地址（默认 http://0.0.0.0:8080），通过 HTTP 协议接收请求，路由匹配和请求处理在 Worker 进程中完成。

配置项（config/config.php）：

Shell 模式

命令行执行单次任务，路由匹配 Route::shell() 定义的路由。

Shell 模式下：

• HTTP 方法自动设为 SHELL
• 路由取 $_SERVER['argv'][1]（自动补 / 前缀）
• 参数取 $_SERVER['argv'][2]，格式为 "key=value&key2=value2"（通过 parse_str 解析为 GET/POST 参数）
• 请求源为 LarkFrame\Request\ShellSource
• 执行完毕后进程退出

Task 模式

常驻内存 Worker 进程执行自定义任务，适合队列消费、定时任务、后台处理等场景。taskname 对应 config/task.php 中定义的任务配置。

配置项（config/task.php）：

任务类需实现 run 静态方法：

• $options：来自配置的 options 键
• $args：来自命令行参数（parse_str 解析后的关联数组）
• 使用 Worker::log() 输出日志（同时写入终端和日志文件），不要使用 echo

运行时文件在 runtime/ 目录下：task-{name}.pid、task-{name}.log、task-{name}.stdout.log

Web 模式（PHP-FPM）

传统 PHP-FPM 部署，每次请求独立进程。站点根目录必须指向 public/，不要指向项目根目录。

访问示例：http://example.com/api

Web 模式下：

• 请求源为 LarkFrame\Request\WebSource（从 $_GET/$_POST/$_SERVER 读取）
• 中间件与 Server 模式行为一致：全局/路由/控制器中间件照常执行， CORS 等响应头中间件在 FPM 下同样生效（404/405 兜底响应也穿全局中间件管道）
• 无需连接池（每次请求独立进程）
• 适合低流量或无法运行常驻进程的环境

License

MIT