6. 逐页拆解:列表与详情
导航聚合页、分类列表页、站点详情页、搜索结果页,加上分页条片段和 404 页,一共六页。 拆法和第 5 章一样:这页干什么、谁调它、控制器给了什么、代码真读了什么、缺文件时什么表现、坑在哪儿,最后一份最小代码。 其中 sort.php 一个文件服务两种地址,pager.php 被 sort、search、daishen、wz_sort、topics 复用,这两页的变量表要看仔细。
6.1 nav.php,网址导航聚合页
视图文件 views/nav.php
- 这页干什么把站点按分类平铺的一整页:搜索框、公告、分类标签、最新、最热、推荐、按分类分组的全部站点。默认模板 106 行。
- 谁调它
FC::nav()在FC:66渲染。路由Router.php:96的/nav.html,兜底形式index.php?s=/nav.html也认。后台「导航菜单」里那条/nav.html就是入口。 - 代码真读到的变量
$cntSort/$cntList/$cntWz(9)、$hotWords(18-23)、$notice(29-32)、$sorts(40-41)、$latest(51)、$mostView(65)、$recommend(79)、$siteGroups与$group/$gs(89-94)。共 13 个。 - 文件缺失时回退 default;全缺则主体位置输出文本
模板不存在:nav.php,照样套 layout,不 fatal。
控制器传进来的变量
| 键 | 来源 | 是什么 |
|---|---|---|
sorts | Sort::ordered() | dtr_sort 行列表 |
siteGroups | Site::groupedBySort(12) | 每项是 ["sort" => dtr_sort 行, "sites" => dtr_list 行列表],只保留有站点的分类,每类最多 12 条 |
latest | Site::latest(30) | dtr_list 行列表 |
mostView | Site::topView(30) | dtr_list 行列表 |
recommend | Site::recommend(30) | dtr_list 行列表 |
hotWords | Site::topView(8) | dtr_list 行列表。注意它就是取 8 个最热站点当热词用的,不是单独的词表 |
notice | Notice::latest(3) | dtr_notice 行列表 |
cntList / cntSort / cntWz | count 三件套 | int |
这一页挂的钩子
| 钩子名 | 触发位置 | 典型用途 |
|---|---|---|
front_nav | FC:65,filter | 整份 $data 可增删键 |
容易踩的地方
- 22 行热门搜索链到
url("site", ["id" => $w["id"]]):url()的 site 分支会查 Slug 登记表拼/list/分类别名/站点别名.html,记不到就退化成数字段地址,由FC::item兜住,不会出现死链。 - 41 行
url("sort", ["id" => $s["id"], "alias" => $s["alias"]]):alias 为空时url()自动用 Slug 登记或 id 兜底,不会生成/list/.html这种死地址。 - 29 行与 89 行都对
notice、siteGroups做了!empty守护,32 行才敢取$notice[0]["content"]。你重写这段必须把守护一起带上,否则站点刚装好、一条公告没有时直接报越界。 - 9 行三个计数键必传,缺了 PHP 8 显示 0 不致命;18 行
if ($hotWords)直接取键,没传就是一串 undefined variable。
最小可用代码
<?php /* views/nav.php */ ?>
<?php if (!empty($notice)): ?>
<div class="notice"><?php echo e($notice[0]['content']); ?></div>
<?php endif; ?>
<div class="tabs">
<?php foreach ($sorts as $s): ?>
<a href="<?php echo url('sort', ['id' => $s['id'], 'alias' => $s['alias']]); ?>"><?php echo e($s['name']); ?></a>
<?php endforeach; ?>
</div>
<?php foreach ($siteGroups as $group): $gs = $group['sites']; if (!$gs) continue; ?>
<section class="grp">
<h3><?php echo e($group['sort']['name']); ?></h3>
<ul class="sites">
<?php foreach ($gs as $s): ?>
<li><a href="<?php echo url('go', ['id' => $s['id']]); ?>" target="_blank" rel="nofollow"><?php echo e($s['name']); ?></a></li>
<?php endforeach; ?>
</ul>
</section>
<?php endforeach; ?>
6.2 sort.php,分类列表页(也被「最新收录」复用)
视图文件 views/sort.php
- 这页干什么面包屑、站点网格、分页条、全部分类侧栏、热门侧栏。一个文件服务两种地址。
- 谁调它两条路。
一:FC::sort()在FC:181渲染。用户访问/list/别名.html或/list/别名/p2.html(Router.php:101-102)先进cat(),它查到分类后在 95 行转手调sort();老地址/sort5.html、/sort别名.html由legacyMove301 到规范地址。
二:FC::newest()在FC:86渲染同一个视图,地址/new.html、/new/p2.html。 - 代码真读到的变量
$sort(6,13,15,23,45,56)、$list_route(7)、$total(17)、$sites(26,30,45)、$cur/$pages(45)、$sorts(54)、$topView(69-72)、$isList/$lr(6,7,12,24,45)、$this(45)。latest只在注释里出现,代码没读。 - 文件缺失时两条 render 路都回退 default;全缺则
模板不存在:sort.php进 layout。分页片段单独算:pager 缺失时列表还在,分页位变成一行文字。
控制器传进来的变量
| 键 | 来源 | 是什么 |
|---|---|---|
sort | dtr_sort 单行;newest 时是合成的 4 键数组 | 最新收录页给的是 ["id"=>0,"parent"=>0,"name"=>"最新收录","alias"=>""],见 FC:76 |
sorts | Sort::ordered() | dtr_sort 行列表 |
sites | 分类页 Site::bySort / 最新页 Site::paged | dtr_list 行列表。分类页每页 20 条按 is_tui DESC, id DESC;最新页每页 24 条按 created_at DESC |
total / pages / cur | 取数结果里的计数 | int。pages = ceil(total/size) |
topView | Site::topView(10) | dtr_list 行列表 |
latest | Site::latest(5) | dtr_list 行列表。传了但默认模板这一页没用到 |
list_route | 仅 newest 分支有 | string = "newest"。视图第 7 行 $lr = $list_route ?? "sort"; |
这一页挂的钩子
| 钩子名 | 触发位置 | 典型用途 |
|---|---|---|
front_sort | FC:180 附近,filter | 分类页整份数据 |
front_newest | FC:85,filter | 最新收录页整份数据 |
容易踩的地方
- 最容易踩的一条:newest 分支不给
list_route,你把它抄过来忘了传,分页就按 route=sort 生成/list/0/p2.html,因为那个合成 sort 的 id 是 0。第 7 行那句$lr = $list_route ?? "sort"与第 45 行的route => $lr要一起留着。 - 第 6 行
(int) $sort["id"] > 0没有判空守护。核心保证分类找不到时先 404(FC:175-178),但插件用 filter 把 sort 键拿掉就翻车:PHP 8 出 warning 并按 0 走 newest 版式。 - 45 行传分页参数:
["cur"=>$cur, "pages"=>$pages, "route"=>$lr, "params"=>$isList ? ["id"=>$sort["id"], "alias"=>$sort["alias"]] : []]。route 是 sort 时分页是路径段/list/xxx/p2.html,是 newest 时是/new/p2.html;params 里的 alias 优先于 Slug 登记表。 - 56 行「全部分类」高亮靠
(int)$s["id"] === (int)$sort["id"]:最新收录页的 sort.id 是 0,全不高亮,这是设计行为,不是 bug。 - 26 行空列表直接给提交引导,不再渲染分页条;
total > 0但只有一页时也只出一页——pager 片段在pages < 2时直接 return。
最小可用代码
<?php /* views/sort.php,分类页与最新收录页共用 */ ?>
<?php
$isList = (int) ($sort['id'] ?? 0) > 0;
$lr = $list_route ?? 'sort';
?>
<nav class="crumb"><a href="<?php echo url('index'); ?>">首页</a> >
<?php echo e($sort['name']); ?></nav>
<p class="sum"><?php echo e($sort['name']); ?>,共 <?php echo (int) $total; ?> 个站点。</p>
<?php if (!$sites): ?>
<p class="empty">这个分类还没有收录,<a href="<?php echo url('apply'); ?>">去提交一个</a>。</p>
<?php else: ?>
<ul class="grid">
<?php foreach ($sites as $si): ?>
<li><a href="<?php echo url('go', ['id' => $si['id']]); ?>" target="_blank" rel="nofollow"><?php echo e($si['name']); ?></a></li>
<?php endforeach; ?>
</ul>
<?php echo $this->partial('pager', [
'cur' => $cur,
'pages' => $pages,
'route' => $lr,
'params' => $isList ? ['id' => $sort['id'], 'alias' => $sort['alias']] : [],
]); ?>
<?php endif; ?>
6.3 site.php,站点详情页
视图文件 views/site.php
- 这页干什么站点信息表、截图、访问与收藏按钮、介绍、同类站点、侧栏。默认模板 94 行。
- 谁调它
FC::site()在FC:206渲染。用户访问/list/分类段/站点段.html(Router.php:103)先进item(),它在 120 行转手调site();老地址/site_5.html被 301。查不到站点直接 404(FC:197)。 - 代码真读到的变量
$site(8,14,21-33,37,44-53,59,64,83-85)、$sort(13,29)、$domain(83)、$related/$r(59,64-70)、页内自算的$isFav(8,45-46) 与$shot(25-26,35-37)。 - 文件缺失时回退 default;全缺则
模板不存在:site.php文本进 layout,不 fatal。
控制器传进来的变量
| 键 | 来源 | 是什么 |
|---|---|---|
site | Site::byId,SELECT * 且不过滤 status | dtr_list 单行,全列。直接猜 id 访问未审核站点也能出详情,别以为前台看不见就安全 |
sort | Sort::byId | dtr_sort 单行或 null。视图 13/29 行按假值分支 |
domain | Site::domainOf($site["url"]) | string,小写去 www 的主机名 |
related | Site::bySort(同分类, 1, 10) | dtr_list 行列表,含本站自己,要循环里 continue 排除;无分类时是空数组 |
links | Link::ordered() | 传了,默认模板这一页没读 |
这一页挂的钩子
| 钩子名 | 触发位置 | 典型用途 |
|---|---|---|
front_site | FC:205 附近,filter | 整份数据,插件可加相关数据键 |
容易踩的地方
- 访问按钮必须走跳转链:
url("go", ["id" => $site["id"]])。直连$site["url"]有两个后果——浏览量一次都不加(addView在 go 里做,FC:734),后台的审核开关也绕过去了。28 行和 44 行都带rel="nofollow"。 - 25 行
site_shot_url($site):后台配了截图 API 就拼 API + domain,否则退回img列;img 也为空时 35 行整个截图块消失,这是正常降级。 - 31 行显示的是
hits(当月)和rhits(当天),总数在view列(32 行)。这三个口径混用是最常见的报数错误。 - 53 行
nl2br(e($site["intro"]))先转义再换行,所以 intro 里写的 HTML 标签不会生效。想让介绍支持富文本,得改成\DTR\Core\Html::clean($site["intro"]),全站口径统一在dtr_intro()。 - 64 行同类列表用
if ((int)$r["id"] === (int)$site["id"]) continue;排自己——related 恰好是从本分类取的 10 条,含本页这个站。 - 8 行
Favorite::has(Member::id(), (int)$site["id"]):收藏按钮只写 data-id 和 data-on,真正的切换打到/fav/{id}.html(Router.php:112,返回 JSON,未登录 401)。不要自己在模板里发 POST。
最小可用代码
<?php /* views/site.php */ ?>
<?php $isFav = \DTR\Core\Member::check() && \DTR\Models\Favorite::has(\DTR\Core\Member::id(), (int) $site['id']); ?>
<article class="site-doc">
<h1><?php echo e($site['name']); ?><small><?php echo e($domain); ?></small></h1>
<?php if ($sort): ?><p class="crumb"><a href="<?php echo url('sort', ['id' => $sort['id'], 'alias' => $sort['alias']]); ?>"><?php echo e($sort['name']); ?></a></p><?php endif; ?>
<?php if ($shot = site_shot_url($site)): ?>
<img class="shot" src="<?php echo e($shot); ?>" alt="<?php echo e($site['name']); ?>">
<?php endif; ?>
<p class="btns">
<a class="btn" href="<?php echo url('go', ['id' => $site['id']]); ?>" target="_blank" rel="nofollow">访问网站</a>
<button class="fav <?php echo $isFav ? 'on' : ''; ?>" data-id="<?php echo (int) $site['id']; ?>"
data-on="<?php echo $isFav ? 1 : 0; ?>">收藏</button>
</p>
<dl class="info">
<dt>总浏览</dt><dd><?php echo (int) $site['view']; ?></dd>
<dt>本月</dt><dd><?php echo (int) $site['hits']; ?></dd>
<dt>今日</dt><dd><?php echo (int) $site['rhits']; ?></dd>
<dt>收录</dt><dd><?php echo e(substr($site['created_at'], 0, 10)); ?></dd>
</dl>
<div class="intro"><?php echo nl2br(e($site['intro'])); ?></div>
<?php $rs = array_filter($related, fn($r) => (int) $r['id'] !== (int) $site['id']); ?>
<aside class="related"><h3>同类站点</h3><ul>
<?php foreach ($rs as $r): ?>
<li><a href="<?php echo url('go', ['id' => $r['id']]); ?>" target="_blank" rel="nofollow"><?php echo e($r['name']); ?></a></li>
<?php endforeach; ?>
</ul></aside>
</article>
6.4 search.php,搜索结果页
视图文件 views/search.php
- 这页干什么重新搜索框、命中列表、分页、分类浏览侧栏。默认模板只有 44 行,是最容易自己重写的一页。
- 谁调它
FC::search()在FC:221渲染。地址/search.html?keyword=xxx&page=2(Router.php:105)。翻页是查询串,不是路径段,和分类列表页不一样。keyword在 FC:218 读,自动 trim。空关键词也出页面,走空结果分支。 - 代码真读到的变量
$kw(8,13,31)、$total(14)、$sites(18,21,31)、$si(22-28)、$cur/$pages(31)、$sorts/$s(39-40)、$this(31)。 - 文件缺失时回退 default;全缺则
模板不存在:search.php进 layout。
控制器传进来的变量
| 键 | 来源 | 是什么 |
|---|---|---|
kw | request("keyword","","GET") | string,用户原文,没做转义处理,输出必须 e() |
sites | Site::search($kw, $page) | dtr_list 行列表:name / keywords / description / domain 四列 LIKE,按 view DESC, id DESC,每页 20 条 |
total / pages | 取数结果 | int,pages = ceil(total/20) |
cur | GET 的 page | int |
sorts | Sort::ordered() | dtr_sort 行列表,侧栏用 |
这一页挂的钩子
| 钩子名 | 触发位置 | 典型用途 |
|---|---|---|
front_search | FC:220 之后,filter | 整份结果数据,插件可加搜索源 |
容易踩的地方
- 8 行的 value 属性里那个 e($kw) 一个字都不能少:kw 是外人提交的 GET 参数,去掉转义就是一个标准的反射型 XSS,改样式时最容易顺手删掉。
- 16-18 行区分「没输入词」和「输入了但没搜到」,判定写的是
$kw === ""。别改成if (!$kw),那样输入 0 会被当成空词。 - 31 行分页把 keyword 原文塞进 params:pager 里调
url("search", ["keyword" => $kw, "page" => $p]),生成/search.html?keyword=%E7%99%BE%E5%BA%A6&page=2,page=1 会被url()省略。漏传 keyword 的话,翻第二页就变成搜空词。 - LIKE 的百分号是直接拼的(
Site.php:130),参数走占位符绑定没有注入风险,但用户输入含 % 时会当通配符用,结果偏多,属已知行为。
最小可用代码
<?php /* views/search.php */ ?>
<form method="get" action="<?php echo url('search'); ?>" class="search-again">
<input name="keyword" value="<?php echo e($kw); ?>">
<button type="submit">搜索</button>
</form>
<?php if ($kw === ''): ?>
<p class="tip">先输入关键词。</p>
<?php elseif (!$sites): ?>
<p class="tip">没有搜到「<?php echo e($kw); ?>」相关站点,<a href="<?php echo url('apply'); ?>">把它提交进来</a>。</p>
<?php else: ?>
<p class="sum">搜到 <?php echo (int) $total; ?> 个结果。</p>
<ul class="grid">
<?php foreach ($sites as $si): ?>
<li>
<a href="<?php echo url('go', ['id' => $si['id']]); ?>" target="_blank" rel="nofollow"><?php echo e($si['name']); ?></a>
<span><?php echo e(cut($si['description'] ?: $si['intro'], 60, '...')); ?></span>
</li>
<?php endforeach; ?>
</ul>
<?php echo $this->partial('pager', [
'cur' => $cur, 'pages' => $pages, 'route' => 'search', 'params' => ['keyword' => $kw],
]); ?>
<?php endif; ?>
6.5 pager.php,分页条片段
视图文件 views/pager.php
- 这页干什么首页、上页、当前页前后各两页、下页、末页。28 行的小片段,被 sort / search / daishen / wz_sort / topics 复用。
- 谁调它没有路由。由视图调
$this->partial("pager", [...]),本组里sort.php:45和search.php:31各调一次。入参完全由调用方现拼,没有默认数组。 - 代码真读到的变量
$cur(5,20,22,25,27)、$pages(6,9,16,21-23,25-27)、$route(7)、$params(8)、页内闭包$mk(12,19-26)、$from/$to(15-16)。 - 文件缺失时partial 一样先回退 default,全缺时这一位输出文本
模板不存在:pager.php,父页其余不受影响。pages < 2时第 10 行直接return,此时输出缓冲已开、capture 收到空串,等于整块不渲染,不报错。
控制器传进来的变量
| 键 | 来源 | 是什么 |
|---|---|---|
cur | 调用方传 | int,第 5 行 max(1, (int)($cur ?? 1)) 兜底 |
pages | 调用方传 | int,第 6 行兜底 0 |
route | 调用方传 | string,url() 的路由名,第 7 行兜底 index |
params | 调用方传 | array,url() 的附加参数,第 8 行兜底空数组 |
这一页挂的钩子
这一页没留钩子位置,插件想插东西得换挂载点。
容易踩的地方
- 12-14 行的
$mk闭包做的是array_merge($params, ["page" => $p])。route 是 sort 时 page 变成路径段/list/xxx/p3.html,是 search 或 daishen 时变成查询串——三种翻页形态由 route 决定,你新增列表页时把 route 名字传对就行。 page = 1时url()不输出页码段(helpers.php:106),首页链接落在无 p 段的规范地址上,这对 SEO 是对的,别改成固定输出 p1。- 15-16 行窗口固定 5 页:
$from = max(1, $cur - 2); $to = min($pages, $from + 4);。靠近尾页时窗口不会右对齐到最后 5 页,是已知的外观取舍。 - 四个键都有 ?? 兜底,漏传不炸;但漏传 route 会静默生成指向首页的分页链接,翻页点了没反应还不出错,最难查。
最小可用代码
<?php /* 调用方写法,三种列表页各一种 */ ?>
<?php // 分类列表:路径段翻页 -->
echo $this->partial('pager', [
'cur' => $cur, 'pages' => $pages,
'route' => 'sort', 'params' => ['id' => $sort['id'], 'alias' => $sort['alias']],
]);
<?php // 搜索结果:查询串翻页,keyword 必须一起传 -->
echo $this->partial('pager', [
'cur' => $cur, 'pages' => $pages,
'route' => 'search', 'params' => ['keyword' => $kw],
]);
<?php // 待审列表:查询串翻页,无附加参数 -->
echo $this->partial('pager', ['cur' => $cur, 'pages' => $pages, 'route' => 'daishen']);
6.6 404.php,找不到页面
视图文件 views/404.php
- 这页干什么一张提示卡加三个按钮:回首页、提交收录、去搜索。12 行。
- 谁调它
FC::notfound()在FC:956渲染,之前 955 行已经http_response_code(404)。到达方式三种:路由表全灭时Router.php:147、显式/404.html(Router.php:126)、以及控制器内部兜底(cat:103、item:131、sort:176、site:198、topic:522、tougao:547、articlePost:627)。 - 代码真读到的变量零个。整个文件没有任何变量,只调
url()。数据面为空,注入面也就为空。 - 文件缺失时回退 default;全缺则 layout 主体输出文本
模板不存在:404.php,HTTP 状态仍是 404(FC 先发),不 fatal。
控制器传进来的变量
| 键 | 来源 | 是什么 |
|---|---|---|
page | FC:956 硬编码 | string 值 404,只给 layout 拼标题「页面不存在_站点名」 |
这一页挂的钩子
| 钩子名 | 触发位置 | 典型用途 |
|---|---|---|
front_404 | FC:953,fire | 反采集插件在这里计数。重写 404 页不用管它,它在控制器侧 |
容易踩的地方
- 7-9 行三个链接用
url("index")、url("apply")、url("search"),返回的是带部署子目录的绝对路径,站点装在子目录也不指错。手写/index.html的话装子目录就 404。 - 别在 404 页里 echo 任何
$_SERVER内容(比如 REQUEST_URI)来「提示哪个地址错了」,那是反射注入面,默认模板刻意保持零输出。 - 开了
app.debug且 layout 渲染抛 Throwable 时,View::capture:115-117会把异常原样抛出去,404 页变异常页,这是调试期正常现象。
最小可用代码
<?php /* views/404.php */ ?>
<div class="nf">
<h1>404</h1>
<p>你要找的页面不存在,可能已经被收录错了。</p>
<p class="nf-btns">
<a class="btn" href="<?php echo url('index'); ?>">回首页</a>
<a class="btn" href="<?php echo url('apply'); ?>">提交收录</a>
<a class="btn" href="<?php echo url('search'); ?>">搜一下</a>
</p>
</div>
内容有问题去论坛发帖,或直接联系老李 QQ 260468289。