# Nex

**Repository Path**: wfdaj/nex

## Basic Information

- **Project Name**: Nex
- **Description**: No description available
- **Primary Language**: PHP
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-05
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# nex

PHP 8.4 的微型 SSR 框架 + 一个轻量论坛示例（帖子 / 标签 / 回复 / 账号 / 头像）。
应用代码只写全局助手函数（`db()`、`view()`、`auth()`…），所有实现都挂在容器里，
因此**换一个绑定就能换掉整条行为**，测试不需要真库、真磁盘、真会话。

需求源头与验收标准是 [`ai.md`](ai.md)（《微型 PHP 框架开发规范》v1.0）；仓库怎么干活、踩过哪些坑见
[`CODEBUDDY.md`](CODEBUDDY.md)。本文件只讲怎么用。

## 环境与安装

- PHP 8.4（用到带类型的类常量、属性提升、`never` 返回类型等）
- 数据库二选一：MySQL 5.7+ / MariaDB，或者 SQLite 3（`pdo_sqlite`，PHP 默认自带）
- Composer 2、PHPUnit 13、PHPStan 2（后三者是开发依赖）

```powershell
composer install

# 装数据库：交互式选择 MySQL 还是 SQLite，建库建表并灌一批测试数据（20 用户 / 100 帖子）
php database/install.php

# 也可以不交互，直接指定驱动（脚本化 / CI 用这个）
php database/install.php --driver=sqlite              # 只建库建表也可以：--no-seed
php database/install.php --driver=mysql --fresh       # --fresh：先清空已有数据再灌
php database/install.php --users=50 --posts=200 --seed=1234   # --seed 固定随机源，数据可复现
```

选完会把 `database.driver`（`mysql` | `sqlite`）写回 `config/database.php`：库和应用的驱动必须是同一个，
而"再手改一次配置"正是最容易漏的一步。MySQL 那条路先 `CREATE DATABASE IF NOT EXISTS` 再建表，
SQLite 那条路只需要在 `storage/database.sqlite` 建文件（目录与表都由脚本处理）。手工装也行：

```powershell
# MySQL（driver = mysql），表结构在 database/schema.sql，内容是 CREATE TABLE IF NOT EXISTS，可重复执行
mysql -u root -p -e "CREATE DATABASE bbs"
mysql -u root -proot bbs -e "source e:/path/to/nex/database/schema.sql"
```

连接参数在 `config/database.php`：MySQL 默认 `127.0.0.1:3306` / `bbs` / `root` / `root` / `utf8mb4`，
SQLite 默认 `storage/database.sqlite`（写绝对路径，相对路径会被按"当前工作目录"解析）。
两套建表语句（`schema.sql` / `schema.sqlite.sql`）表结构一致，换驱动时应用代码一行都不用改。
灌进去的测试数据用同一个密码：登录示例 `seed01@nex.test` / `password`。

把 Web 根指向 `public/`，入口是 `public/index.php`；`storage/{cache,logs,sessions,uploads}` 需要可写
（目录由各实现按需自建，`0700`）。

前端资源是直接落盘的静态文件、**没有构建步骤**：`public/css/bootstrap.min.css`（Bootstrap 5.3.8）、
`public/css/app.css`（只放 Bootstrap 没有的规则，如 `.avatar`）、`public/js/bootstrap.min.js`
（另有 `public/js/htmx.min.js`，已就位但未使用）。模板里不写 `<style>`，样式一律用 Bootstrap
工具类 + `app.css`。

## 快速开始：路由表优先，未命中即"URL 就是文件路径"

默认规则：路径第 1 段 → `app\controller` 下的类，第 2 段 → 方法（省略即 `index`），第 3 段起 → 位置参数。
只有文件映射表达不了的地址（根路径 `/`、带连字符的路径、要把某个地址指向另一个控制器）才写进
`app/routes.php`：**表里有的以表为准，其余照旧按文件路径映射**（表为空或删掉该文件＝全部回退）。

```php
// app/routes.php：'路径模式' => [控制器::class, '方法名']；{name} 是占位符，匹配到的一段按顺序传参
return [
    '/'                => [Post::class, 'index'],
    // '/post/show/{id}' => [Post::class, 'show'],   // 这类地址本就能按文件路径访问，写进表只是显式声明
];
```

| URL | 处理 | 说明 |
|---|---|---|
| `/` | `Post::index()` | 由 `app/routes.php` 声明：首页＝帖子列表（与 `/post` 同一段代码；旧别名 `/home` 已删） |
| `/post` | `Post::index()` | 帖子列表，支持 `?tag={id}`、`?page={n}` |
| `/post/show/{id}` | `Post::show()` | 详情（浏览量 +1、标签、回复） |
| `/post/create`、`/post/store` | `Post::create()` / `store()` | 发帖（需登录） |
| `/post/edit/{id}`、`/post/update/{id}` | `Post::edit()` / `update()` | 改帖（需登录 + 作者本人） |
| `/post/delete/{id}` | `Post::delete()` | 删帖（需登录 + 作者本人） |
| `/reply/store/{postId}` | `Reply::store()` | 回帖（需登录） |
| `/reply/edit/{id}`、`/reply/update/{id}` | `Reply::edit()` / `update()` | 改回复（需登录 + 作者本人） |
| `/reply/delete/{id}` | `Reply::delete()` | 删回复（需登录 + 作者本人；回复数同事务 -1） |
| `/tag` | `Tag::index()` | 标签墙 + 各标签帖子数 |
| `/profile/avatar` | `Profile::avatar()` | 上传头像（需登录，按内容判定 png/jpg/gif/webp，≤ 2 MB） |
| `/avatar/show/{id}` | `Avatar::show()` | 输出头像图片（公开；上传目录不在 `public/` 下，必须由控制器读出来） |
| `/login`、`/register`、`/logout/store`、`/profile`、`/user/…` | 账号相关 | 昵称/密码/头像等 |

写操作统一由全局 `CsrfGuard` 中间件保护（表单里要有 `_token`）；没带对令牌抛
`TokenMismatchException`，由 `ErrorHandler` 映射成 **419**。

## 如何使用助手函数

助手函数是应用与框架交互的**唯一入口**，定义在 `core/helpers.php`（22 个）与 `app/helpers.php`
（7 个，应用自有）。它们都只有"取绑定 → 转发"两三行，没有任何业务逻辑。

应用代码分三层：**控制器**（`app/controller`，只管 HTTP：取输入、校验、授权、渲染、跳转）、
**服务**（`app/service`，管跨表事务、跨模型拼装与应用级规则）、**模型**（`app/model`，只管一张表怎么读写）。
判据与边界见 `CODEBUDDY.md` 的"应用分层"一节。

```php
// 读数据：服务层把"帖子 + 作者 map + 分页 + 每页条数"一次拼好（控制器的 index/show 因此只有几行）
$data = post_service()->listing(request()->int('tag') ?: null, request()->int('page', 1), request()->path);
return view('post/index', $data);          // 服务返回的标签不存在时是 null，由控制器决定回 404

// 校验：失败会自动存闪存 + PRG 回跳，成功返回"可以入库的字段"
validate(request()->only(['title', 'body']), [
    'title' => 'required|string|min:2|max:' . \app\service\PostService::TITLE_MAX,
    'body'  => 'required|string|min:2|max:' . \app\service\PostService::BODY_MAX,
], '/post/create');

// 写库：跨表一致性（发帖 + 标签、删帖 + 回复 + 关联）由服务层用事务兜住
$tags = post_service()->parseTags(request()->string('tags'));   // 切分/去空白/去重/限额，一次拿到结果与提示
$postId = post_service()->create((int) $current_user_id, $title, $body, $tags['names']);

flash('status', '发布成功');
redirect('/post/show/' . $postId);          // never：发完 Location 就结束请求
```

高频的几个：`config()`、`view()`、`e()`（**唯一**的输出转义通道）、`url()`、`redirect()`/`back()`、
`request()`、`session()`/`flash()`/`old()`/`errors()`/`validate()`、`csrf()`、`auth()`/`gate()`、
`db()`、`storage()`、`cache()`、`logger()`、`response()`、`resolve()`/`container()`。

## 如何写视图（继承、段、片段）

视图是**原生 PHP**（没有模板编译器），渲染在独立作用域里：模板只拿得到传进去的变量和 `$this`
（本次渲染的 `core\view\ViewContext`，也就是模板语法本身），碰不到渲染器内部。

```php
// app/view/layout/app.php：布局
<title><?= e($this->yield('title', (string) config('app.name'))) ?></title>
<main><?= $this->yield('content') ?></main>

// app/view/post/index.php：页面
<?php $this->extends('layout/app'); ?>
<?php $this->section('title', $title); ?>
<?php $this->section('content'); ?>
    <h1><?= e($title) ?></h1>
    <?= $this->include('layout/avatar', ['user' => $author]) ?>
<?php $this->endsection(); ?>
```

- `extends('layout/app')`：声明父模板（只声明一次；`include` 进来的片段不能再 `extends`）。
  先执行子模板、再执行父模板，最终页面是父模板的渲染结果——子模板段以外的输出会被丢掉。
- `section('title', 'Page Title')`：直接给内容的短段；`section('sidebar')` … `endsection()`：缓冲一段大 HTML（段可以嵌套）。
- `yield('name', '默认值')`：在父模板里输出段内容。**不自动转义**——段里通常是 HTML，要转义自己 `e()`。
- `parent()`：写在子模板的段里，占位"父模板同名段的内容"；父模板要用 `section('sidebar', '…')` 提供这份内容。
  父模板只写 `yield('sidebar', '默认')` 是没有可继承内容的，会直接报错。
- `include('view/name', ['k' => 'v'])`：渲染片段。与 `view()` 一样**只吃显式传的数据**（不隐式继承调用方变量），
  区别是共用段表：片段里 `yield()` 能读到本页的段，它定义的段也能被父模板读到。

模板写错会当场抛 `RuntimeException`（`extends` 两次、继承成环、段漏 `endsection()`、`parent()` 用错位置），
不会靠"页面看着还行"蒙过去。

仓库里 12 个页面模板全是这么写的：论坛各页继承 `app/view/layout/app.php`，登录/注册继承
`app/view/layout/auth.php`（居中卡片，样式在 `public/css/auth.css`），头像片段用
`$this->include('layout/avatar', ['user' => $author, 'size' => 'avatar-sm'])` 引。
父模板与片段自身不 `extends`，`view()` 助手仍在（片段之外想"另起一次渲染"时用）。

## 如何替换容器绑定

测试里换绑定就是换实现；应用里换绑定就是换行为（例如把 `db` 指向另一个库、把 `cache` 换成 Redis）。

```php
$container = App::boot();              // 每次都是全新容器，用例之间天然隔离

// 1) 测试专用：swap($abstract, $instance) 立刻生效，返回"还原闭包"
$container->swap('db', new FakeDatabase());          // 不连库
$container->swap('session', new FakeSession());      // 不 session_start()
$container->swap('redirect', new FakeRedirector());  // 真实现会 exit，替身改抛错

// 2) 应用专用：在 app/bootstrap.php 里注册自己的绑定（本文件同样能覆盖 core 的默认绑定）
$container->singleton('users', static fn (): UserModel => new UserModel());
$container->bind('report', static fn (Container $c) => new ReportService($c->make('db')));  // 每次都重建
```

要点：

- 绑定是**惰性**的（解析时才构造），所以 `App::boot()` 不会连库、不会 `session_start()`。
- 工厂里**不要**用全局助手（此刻全局访问点可能还没登记），工厂第一个参数就是当前容器：
  `static fn (Container $c) => new Foo($c->make('bar'))`。
- "替换点"通常在助手背后的**协作者**上：`auth(): Auth` 是具体类，要换身份来源就
  `swap('session', …)`，而不是去换 `Auth`。
- 未绑定的服务 `make()` 会抛 `RuntimeException`（引导之前抛的是"容器尚未引导"，两者不会混）。

## 如何新增服务与助手函数

五步，照 `url()` / `storage()` / `gate()` 的样子做：

1. **定契约**：有外部 IO / 全局状态才抽接口（`SessionInterface`、`ConnectionInterface`、
   `FilesystemInterface`…）；纯逻辑或值对象直接写具体类（`Validator`、`Paginator`、`UploadedFile`）。
2. **写实现**：构造签名要与 `App::boot()` 里的工厂一致（`App.php` 顶部的注释列了全部签名）。
3. **加助手**：在 `core/helpers.php` 里加"取绑定 → 转发"，并用 `function_exists()` 包住
   （应用侧 `app/helpers.php` 排在它之前加载，同名即整体覆盖）。
4. **加绑定**：在 `App::boot()` 里 `singleton(...)`；要注入依赖的中间件按**类名**绑定
   （`Pipeline` 解析中间件时优先走容器）。
5. **补测试**：`tests/core/...` 测逻辑，`tests/helpers/...` 测"换绑定即换行为"，替身放
   `tests/fakes/`。文件 IO 类的实现只写 `sys_get_temp_dir()` 下的临时目录，`tearDown` 清理。

应用自己的东西（模型、服务）不进 `core/`：绑定写在 `app/bootstrap.php`，助手写在
`app/helpers.php`（`users()`/`posts()`/`tags()`/`replies()`/`post_service()`/`reply_service()` 就是这样）。
应用侧的服务照 `app/service/PostService.php` 的样子写：无构造依赖、内部经助手取模型、返回
"视图数据数组 / 业务主键 / null"，不碰 `request()`/`flash()`/状态码。core 因此能整目录搬走。

## 如何跑测试

```powershell
php vendor/bin/phpunit                                  # 全量
php vendor/bin/phpunit tests/core/database/QueryChainTest.php
php vendor/bin/phpunit --filter OrderBy                 # 按方法名过滤

php vendor/bin/phpstan analyse --no-progress             # level 6，配置在 phpstan.neon
```

测试不依赖真实数据库、缓存或外部服务：`swap('db', FakeDatabase)`、`swap('session', FakeSession)`、
`swap('redirect', FakeRedirector)`、文件 IO 类只写系统临时目录。`MysqlConnection` 从未连真库，
它的查询链语义由 `tests/core/database/QueryChainTest.php` 用替身钉住。

唯一的例外是 SQLite：它没有服务、不需要配置，所以 `SqliteConnectionTest` 在**系统临时目录**里的
文件库上真跑一遍查询链（方言写错了替身看不出来）；建表语句与模型的列名一致性也由它守着。

## 目录结构

```
app/          用户代码：routes.php（路由表）/ controller（HTTP）/ service（跨表编排与业务规则与测试数据）/ model（单表读写）/ middleware / view
config/       配置（app / database / filesystem / forum），App::boot() 平坦合并
core/         框架核心：Container / Config / App / ErrorHandler / Validator / Paginator
              cache database filesystem http logging routing security session view
database/     建表语句 schema.sql（MySQL）/ schema.sqlite.sql（SQLite），安装脚本 install.php
public/       入口 index.php（require autoload → boot → 注册错误处理 → dispatch）
storage/      cache / logs / sessions / uploads（被 .gitignore 忽略，需可写）
tests/        镜像源码树；fakes/ 放内存替身
```

## 已知取舍（细节见 CODEBUDDY.md）

- `view()` 返回 `string`、`redirect()`/`back()` 返回 `never`（与 ai.md 的 `: Response` 写法不同，见
  `CODEBUDDY.md` 的差距表）。
- 容器用 `bind`/`singleton`/`make`/`has`/`swap` 表达 `set`/`get`/`has`/`singleton`/`setInstance`，
  没有 `reset()`——"每个用例一份全新容器"替代了它。
- 路由不看 HTTP 方法：写方法靠"全局 CSRF 守卫 + 控制器自己的必填字段/显式令牌校验"兜住。
- 帖子正文按**纯文本**渲染（`nl2br(e($body))`）：没有富文本/Markdown，也就没有存储型 XSS 的口子。
- 上传目录在 `storage/uploads`（非 `public/`），文件名随机、后缀取自**文件头内容检测**（不信任原名与客户端 MIME），
  并按随机名前两位 hex 分 256 个桶存放；允许的图片类型在 `config/upload.php` 配置；对外展示由控制器读取后按 `Content-Type` 输出。