开发文档 ›全部章节 ›逐页拆解 ›逐页拆解:外壳与首页

5. 逐页拆解:外壳与首页

这一章把默认模板的 layout.php、header.php、footer.php、index.php 一页一页拆开讲: 这页干什么、谁调它、控制器传进来哪些键、代码真读到了哪些、文件缺失时什么表现、容易踩在哪儿,最后附一份能直接抄的最小代码。 读法对着第 3 节那套规矩,结论全部出自默认模板与主程序代码,没写的就是没有。

5.1 layout.php,全站外壳

视图文件 views/layout.php

  • 这页干什么整张 HTML 骨架:head、SEO 标题、配色变量、页头页脚、内容槽。每套模板都该有自己的这一份,缺了整套页面就没有样式和脚本。
  • 谁调它没有一个地址直接渲染它。View::render() 先 capture 子视图,再把结果塞进 $__content 交给 layout,见 app/core/View.php:63-74。插件用 View::wrap() 出整页时也走它。
  • 代码真读到的变量真读到的:$__content(97)、$page(8,84,86,92,94,104)、$site(14-17)、$sort(18-21)、$article(22-25)、$kw(26-27)、$topic(41-42)、$seo_title(62-63)、$this(91,99)。共 13 个,这就是全集。
  • 文件缺失时当前模板没有 layout.php 会回退 default 那份;两套都没有时 render() 里 is_file 判假,子视图 HTML 原样吐给浏览器。表现为:没有 <head>、没有样式没有图标,内容糊在浏览器默认样式上。不报错、不白屏,一眼就能认出来。

控制器传进来的变量

键来源是什么
__contentView.php:65,69 引擎注入string。子视图渲染好的完整 HTML,echo 时不要再转义
pageFC 各方法硬编码string,比如 index、sort、site。用来出 body 的 class
site仅站点详情页,FC:202dtr_list 单行或不存在。layout 只读它推标题
sort分类页、详情页dtr_sort 单行或不存在
article文章详情页dtr_wz 单行,layout 只用 title 和 keywords
kw搜索页 FC:221string,用户输入的关键词原文
topic专题页dtr_zt 行,用 name 和 description
seo_title插件页才给string。给了就完全接管 title,不再走推导链
conf / appindex.php:21-23 全局共享两个数组,所有视图都能看到

这一页挂的钩子

钩子名触发位置典型用途
front_headlayout.php:84给 head 里插 meta、样式、脚本,插件统计代码就挂这里
front_body_startlayout.php:87body 刚打开,适合挂全站横幅、客服码
front_slot_headlayout.php:92页头下方的通栏广告位
front_body_endlayout.php:104body 收尾前,插脚本的地方

容易踩的地方

  • 第 14-21 行是按 isset 猜 site、sort 来推标题的:任何页面只要数据里带了这两个键,标题就会被改写,跟 page 是什么无关。插件借你的 layout 传数据时注意别撞上。
  • 83 行和 103 行输出 Config::get("site_head")、site_foot 时不过 e(),这是刻意留的原始 HTML 注入点,你重排 layout 时别顺手加转义,后台填的代码就失效了。
  • $this->partial() 只在引擎 include 时才有 $this。把 layout 的内容复制进某个函数里跑,立刻 Fatal: Call to a member function partial() on null。
  • 第 8 行 $page = $page ?? ""; 已经兜底,控制器忘传 page 不炸,但 body 的 class 会变成 page-,你的按页样式全不生效,排查时先 F12 看这个 class。

最小可用代码

<?php /* views/layout.php,最小可用版,抄过去改样式 */ ?>
<!doctype html>
<html lang="zh-cn">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<?php
    // 标题推导链:插件给的 seo_title 最优先,其次按数据里有什么猜,最后退回站名
    $__t = '';
    if (!empty($seo_title)) {
        $__t = (string) $seo_title;
    } elseif (!empty($site)) {
        $__t = $site['name'] . ' - ' . dtr('name');
    } elseif (!empty($article)) {
        $__t = $article['title'] . ' - ' . dtr('name');
    } else {
        $__t = dtr('name');
    }
?>
<title><?php echo e($__t); ?></title>
<link rel="stylesheet" href="<?php echo tpl_url('style.css'); ?>">
<?php \DTR\Core\Hooks::fire('front_head', ['page' => $page ?? '']); ?>
</head>
<body class="page-<?php echo e($page ?? ''); ?>">
<?php \DTR\Core\Hooks::fire('front_body_start'); ?>
<?php echo $this->partial('header', ['page' => $page ?? '']); ?>
<main class="wrap"><?php echo $__content; ?></main>
<?php echo $this->partial('footer', ['page' => $page ?? '']); ?>
<?php \DTR\Core\Hooks::fire('front_body_end', ['page' => $page ?? '']); ?>
</body>
</html>

5.2 header.php,页头与主导航

视图文件 views/header.php

  • 这页干什么logo、主导航、提交收录按钮、登录态。它是片段,不是整页。
  • 谁调它只被 layout.php:91 调:$this->partial("header", ["page" => $page])。凡是走了 layout 的地址都间接到达,包括插件页。partial 不再套 layout,见 View.php:77-80。
  • 代码真读到的变量代码真读的:$navs(9,28)、$isLog(10,39)、$me(11,40)、循环里的 $n、$href、$ext(29-31)。控制器给的那些键一个都不接,导航和登录态全在页内现查数据库。
  • 文件缺失时partial() 同样先回退 default;两套都没有时页脚位置直接输出文本 模板不存在:header.php,页面其余部分照常渲染,不 fatal。

控制器传进来的变量

键来源是什么
pagelayout:91 传入string。注意:默认模板的 header 代码其实没读它,只有注释里提
navs本页现查 Nav::ordered(),header.php:9dtr_nav 行列表:id, name, url, icon, sort_order,按 sort_order 排
isLog本页现查 Member::check()bool
me本页现查 Member::current()dtr_user 单行或 null,只读 nickname / username
conf / app全局共享数组

这一页挂的钩子

钩子名触发位置典型用途
front_nav_extraheader.php:34往主导航右侧追加链接,功能类插件用它

容易踩的地方

  • 第 27 行首页高亮写死 nav_on(site_url("/")),而 nav_on() 对根路径特判只认当前地址是 / 或 /index.html。访问 /index/p2.html 时首页链接不再高亮,这是核心行为,不是你的 bug。
  • 29 行用 preg_match("#^https?://#i", trim($n["url"])) 判外链:外链强制 target=_blank rel=nofollow,而且永远不加 on 类。后台导航里填 nav.html 这种不带斜杠的内链,会被 nav_url() 补成 /nav.html,能正常匹配。
  • 16 行探测 is_file(DTR_TPL . tpl() . "/public/pc/img/logo.png"):新模板目录没放 logo 就自动退化成文字/圆点,不会给你留一个裂开的图。
  • 40 行 $me["nickname"] ?: $me["username"]:会话还在但用户行被删时 current() 返回 null,PHP 8 这里出一条 warning 而不是致命错误,看到 Trying to access array offset on null 先怀疑数据被删。

最小可用代码

<?php /* views/header.php */ ?>
<?php
    $navs = \DTR\Models\Nav::ordered();
    $isLog = \DTR\Core\Member::check();
    $me    = \DTR\Core\Member::current();
?>
<header class="site-head">
  <a class="brand" href="<?php echo url('index'); ?>">
    <?php if (is_file(DTR_TPL . tpl() . '/public/pc/img/logo.png')): ?>
      <img src="<?php echo tpl_url('public/pc/img/logo.png'); ?>" alt="<?php echo e(dtr('name')); ?>">
    <?php else: ?>
      <span class="brand-dot"></span><?php echo e(dtr('name')); ?>
    <?php endif; ?>
  </a>
  <nav class="nav">
    <a class="<?php echo nav_on(site_url('/')) ? 'on' : ''; ?>" href="<?php echo site_url('/'); ?>">首页</a>
    <?php foreach ($navs as $n): ?>
      <?php $ext = (bool) preg_match('#^https?://#i', trim($n['url'])); ?>
      <a href="<?php echo nav_url($n['url']); ?>"
         <?php if ($ext): ?>target="_blank" rel="nofollow"<?php endif; ?>
         class="<?php echo (!$ext && nav_on($n['url'])) ? 'on' : ''; ?>"><?php echo e($n['name']); ?></a>
    <?php endforeach; ?>
    <?php \DTR\Core\Hooks::fire('front_nav_extra', ['navs' => $navs]); ?>
  </nav>
  <div class="head-right">
    <a class="btn" href="<?php echo url('apply'); ?>">提交收录</a>
    <?php if ($isLog): ?>
      <a href="<?php echo url('user'); ?>"><?php echo e($me['nickname'] ?: $me['username']); ?></a>
    <?php else: ?>
      <a href="<?php echo url('login', ['r' => current_url()]); ?>">登录</a>
    <?php endif; ?>
  </div>
</header>

5.3 footer.php,页脚

视图文件 views/footer.php

  • 这页干什么底部链接、页脚广告、版权与备案号、免责声明。
  • 谁调它layout.php:99 的 $this->partial("footer", ["page" => $page]),跟 header 一样是片段。
  • 代码真读到的变量$footLinks(6,15,23)、$footRaw(7,8)、$line(8-13)、$kv(13-15)、$fl(24)、$disclaimer(18,48-49)、$footAd(32-33)。控制器变量一个都不接。
  • 文件缺失时两套都缺时页脚位置输出文本 模板不存在:footer.php,不 fatal。

控制器传进来的变量

键来源是什么
pagelayout:99 传入string,本页代码不读
footLinks本页解析 tplcfg("foot_link")二维数组,每项 [名称, 地址],来自每行「名称,地址」的 explode
disclaimertplcfg("foot_disclaimer")string
footAdConfig::get("ad_footer")string,HTML 原文,只有 ad_enable 为 1 才输出
conf / app全局共享数组

这一页挂的钩子

钩子名触发位置典型用途
front_footer_extrafooter.php:26插件往页脚追加内容,留言板、统计都从这里出

容易踩的地方

  • 26 行的 Hooks::fire("front_footer_extra") 是插件的出口,抄别人模板时删掉它,那个插件的页脚模块就永远不出现,文件第 5 行注释专门提醒过。
  • 32-33 行 echo $footAd 不转义,但要先满足后台 ad_enable 等于 1 且 ad_footer 非空;后台填进去的本来就是 HTML。
  • 7 行兼容字面 \n、\r\n、\n 三种换行写法,但每行必须是「名称,地址」两段,名称为空的行会被 14 行静默丢掉,配置里少打一个逗号就少一条链接。
  • 24 行 nav_url($fl[1]) 不过 e():地址里含引号会破坏标签,这是「信任后台配置」的既定行为,你改模板别把这个写法扩散到前台可控数据上。

最小可用代码

<?php /* views/footer.php */ ?>
<?php
    $raw   = (string) tplcfg('foot_link', '');
    $links = [];
    foreach (preg_split("/[\r\n]+/", str_replace(['\r\n', '\n', '\\n'], "\n", $raw)) as $line) {
        $kv = explode(',', $line, 2);
        if (count($kv) === 2 && trim($kv[0]) !== '') { $links[] = [trim($kv[0]), trim($kv[1])]; }
    }
    $ad = \DTR\Core\Config::get('ad_enable') === '1' ? (string) \DTR\Core\Config::get('ad_footer', '') : '';
?>
<footer class="site-foot">
  <div class="foot-links">
    <?php foreach ($links as $l): ?><a href="<?php echo nav_url($l[1]); ?>"><?php echo e($l[0]); ?></a><?php endforeach; ?>
  </div>
  <?php if ($ad !== ''): ?><div class="foot-ad"><?php echo $ad; ?></div><?php endif; ?>
  <p class="copy"><?php echo e(dtr('name')); ?> &copy; <?php echo date('Y'); ?>
     <?php echo e(\DTR\Core\Config::get('icp', '')); ?></p>
  <?php echo tplcfg('foot_disclaimer', ''); ?>
  <?php \DTR\Core\Hooks::fire('front_footer_extra'); ?>
</footer>

5.4 index.php,首页

视图文件 views/index.php

  • 这页干什么整站的门面:搜索、统计条、公告、推荐位、最近来访、分类区、最新收录、文章、热榜、友链。默认模板这一份 191 行。
  • 谁调它FrontController::index() 在 FC:46 调 render("index", $data)。地址是 / 和 /index.html(Router.php:93-94)。路由表里还有一条 /index/p2.html,但 index() 根本不接页码参数,那一段被静默忽略,首页没有翻页,别去实现它。
  • 代码真读到的变量$cntList/$cntSort/$cntWz/$cntApply(17-20)、$notice(29,32-33,153,184-187)、$recommend(42,47)、$recent(58,63)、$sorts(78,83)、$latest(91,96)、$articles(115,120)、$topView(135,140)、$links(166,171)。共 20 个,全部对得上 FC 键。
  • 文件缺失时缺 index.php 先回退 default;两套都缺则 layout 主体里输出文本 模板不存在:index.php,头和脚照常,不 fatal。

控制器传进来的变量

键来源是什么
sortsSort::ordered()dtr_sort 行列表,全列
recommendSite::recommend(16)dtr_list 行列表,条件 is_tui = 1 按 id 排
latestSite::latest(12)dtr_list 行列表,status=1 按 created_at DESC
topViewSite::topView(10)dtr_list 行列表,按 view DESC
recentSite::recentHits(20)dtr_list 行列表,条件 status=1 AND last_hit > 0,按 last_hit DESC
noticeNotice::latest(5)dtr_notice 行列表:id, content, created_at
linksLink::ordered()dtr_link 行列表:id, name, url,按 id 排
articlesArticle::latest(8)dtr_wz 行列表,VISIBLE 条件,按 publish_at DESC
cntListSite::count(status = 1)int,已收录站点数
cntWzArticle::countLive()int,可见文章数
cntSortSort::count(1)int,分类总数
cntApplyApply::pendingCount()int,待审提交数。注意统计页那个同名键是全部提交数,口径不一样

这一页挂的钩子

钩子名触发位置典型用途
front_indexFC:45,filter拿到整个 $data 数组,改完原样 return。想加首页模块不用改核心,挂这里
front_slot_index首页通栏位广告位、活动条

容易踩的地方

  • 42/78/91/115/135/166 行都是 tplcfg(...) == "1" && $recommend 这种裸真值判断:FC 少传一个键就是 undefined variable warning。要学 58 行的 !empty($recent),那才是安全写法。插件用 front_index 把某个键 unset 掉,首页就会刷一片提示噪音。
  • 63 行的截断是计数 break 不是 array_slice:$hn = max(1,(int)tplcfg("hit_num","20")); foreach ($recent as $h) { if (++$hi > $hn) break; },改这段别把 $hi 的初始化弄丢,丢了就是每次进循环都从 1 开始,只显示一条。
  • 33 行用 count($notice) > 1 决定要不要「更多」链接,它依赖 187 行输出的 dtrNotice() 那段脚本;184 行的 if (!empty($notice)) 保证有公告才输出脚本。这两处必须同进退,拆开改就坏。
  • 104 行 cut($si["name"], 6) 省了第三参,cut() 的默认后缀是 ...(helpers.php:254),跟满篇的 cut($x, 12, "") 行为不同,你要统一省略号样式得逐处看。
  • 105 行 $si["description"] ?: $si["intro"]:两列都可能是空串或 null,cut() 内部先 strip_tags((string)) 兜底,所以传 null 不炸。
  • 121 行 mb_substr($a["created_at"], 5, 5) 直接按 datetime 字符串切月份日期;字段被截坏时显示乱日期而不是报错。
  • 166 行 !plugin_active("friendlink"):装了并且开着友链插件时,核心那块友链自动隐藏。用户报「首页友链不见了」,先去插件管理看状态,别改模板。
  • 11 行搜索表单 GET 提交到 url("search"),落地地址是 /search.html?keyword=xxx。

最小可用代码

<?php /* views/index.php,只留骨架,样式自己配 */ ?>
<section class="hero">
  <form method="get" action="<?php echo url('search'); ?>">
    <input name="keyword" placeholder="搜索站点" value="">
    <button type="submit">搜索</button>
  </form>
  <p class="stat">共 <?php echo (int) $cntList; ?> 个站点、<?php echo (int) $cntSort; ?> 个分类、
     <?php echo (int) $cntWz; ?> 篇文章,<?php echo (int) $cntApply; ?> 条待审。</p>
</section>

<?php if (!empty($notice)): ?>
  <div class="notice-bar"><?php echo e($notice[0]['content']); ?>
    <?php if (count($notice) > 1): ?><a href="<?php echo url('index'); ?>">更多</a><?php endif; ?>
  </div>
<?php endif; ?>

<?php if (tplcfg('show_recommend', '1') == '1' && !empty($recommend)): ?>
  <section class="blocks">
    <h2>推荐站点</h2>
    <div class="grid">
      <?php foreach ($recommend as $r): ?>
        <a class="card" href="<?php echo url('go', ['id' => $r['id']]); ?>" target="_blank" rel="nofollow">
          <b><?php echo e(cut($r['name'], 12, '')); ?></b>
          <span><?php echo e(cut($r['description'] ?: $r['intro'], 40, '...')); ?></span>
        </a>
      <?php endforeach; ?>
    </div>
  </section>
<?php endif; ?>

<?php if (!empty($recent)): ?>
  <?php $limit = max(1, (int) tplcfg('hit_num', '20')); $i = 0; ?>
  <section class="blocks"><h2>最近来访</h2><ul>
    <?php foreach ($recent as $h): if (++$i > $limit) break; ?>
      <li><a href="<?php echo url('site', ['id' => $h['id']]); ?>"><?php echo e($h['name']); ?></a>
          <em><?php echo (int) $h['rhits']; ?></em></li>
    <?php endforeach; ?>
  </ul></section>
<?php endif; ?>

<?php foreach ($sorts as $s): ?>
  <section class="cat">
    <h3><a href="<?php echo url('sort', ['id' => $s['id'], 'alias' => $s['alias']]); ?>"><?php echo e($s['name']); ?></a></h3>
  </section>
<?php endforeach; ?>

<?php if (!empty($articles)): ?>
  <section class="blocks"><h2>最新文章</h2><ul>
    <?php foreach ($articles as $a): ?>
      <li><a href="<?php echo url('wzshow', ['id' => $a['id']]); ?>"><?php echo e($a['title']); ?></a>
          <time><?php echo e(mb_substr($a['created_at'], 5, 5)); ?></time></li>
    <?php endforeach; ?>
  </ul></section>
<?php endif; ?>

<?php if (!plugin_active('friendlink') && !empty($links)): ?>
  <section class="links"><?php foreach ($links as $l): ?>
    <a href="<?php echo e($l['url']); ?>" target="_blank" rel="nofollow"><?php echo e($l['name']); ?></a>
  <?php endforeach; ?></section>
<?php endif; ?>

内容有问题去论坛发帖,或直接联系老李 QQ 260468289。