开发文档 ›全部章节 ›逐页拆解 ›逐页拆解:列表与详情

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。

控制器传进来的变量

键来源是什么
sortsSort::ordered()dtr_sort 行列表
siteGroupsSite::groupedBySort(12)每项是 ["sort" => dtr_sort 行, "sites" => dtr_list 行列表],只保留有站点的分类,每类最多 12 条
latestSite::latest(30)dtr_list 行列表
mostViewSite::topView(30)dtr_list 行列表
recommendSite::recommend(30)dtr_list 行列表
hotWordsSite::topView(8)dtr_list 行列表。注意它就是取 8 个最热站点当热词用的,不是单独的词表
noticeNotice::latest(3)dtr_notice 行列表
cntList / cntSort / cntWzcount 三件套int

这一页挂的钩子

钩子名触发位置典型用途
front_navFC: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 由 legacyMove 301 到规范地址。
    二: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 缺失时列表还在,分页位变成一行文字。

控制器传进来的变量

键来源是什么
sortdtr_sort 单行;newest 时是合成的 4 键数组最新收录页给的是 ["id"=>0,"parent"=>0,"name"=>"最新收录","alias"=>""],见 FC:76
sortsSort::ordered()dtr_sort 行列表
sites分类页 Site::bySort / 最新页 Site::pageddtr_list 行列表。分类页每页 20 条按 is_tui DESC, id DESC;最新页每页 24 条按 created_at DESC
total / pages / cur取数结果里的计数int。pages = ceil(total/size)
topViewSite::topView(10)dtr_list 行列表
latestSite::latest(5)dtr_list 行列表。传了但默认模板这一页没用到
list_route仅 newest 分支有string = "newest"。视图第 7 行 $lr = $list_route ?? "sort";

这一页挂的钩子

钩子名触发位置典型用途
front_sortFC:180 附近,filter分类页整份数据
front_newestFC: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> &gt;
  <?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。

控制器传进来的变量

键来源是什么
siteSite::byId,SELECT * 且不过滤 statusdtr_list 单行,全列。直接猜 id 访问未审核站点也能出详情,别以为前台看不见就安全
sortSort::byIddtr_sort 单行或 null。视图 13/29 行按假值分支
domainSite::domainOf($site["url"])string,小写去 www 的主机名
relatedSite::bySort(同分类, 1, 10)dtr_list 行列表,含本站自己,要循环里 continue 排除;无分类时是空数组
linksLink::ordered()传了,默认模板这一页没读

这一页挂的钩子

钩子名触发位置典型用途
front_siteFC: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。

控制器传进来的变量

键来源是什么
kwrequest("keyword","","GET")string,用户原文,没做转义处理,输出必须 e()
sitesSite::search($kw, $page)dtr_list 行列表:name / keywords / description / domain 四列 LIKE,按 view DESC, id DESC,每页 20 条
total / pages取数结果int,pages = ceil(total/20)
curGET 的 pageint
sortsSort::ordered()dtr_sort 行列表,侧栏用

这一页挂的钩子

钩子名触发位置典型用途
front_searchFC: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。

控制器传进来的变量

键来源是什么
pageFC:956 硬编码string 值 404,只给 layout 拼标题「页面不存在_站点名」

这一页挂的钩子

钩子名触发位置典型用途
front_404FC: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。