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>、没有样式没有图标,内容糊在浏览器默认样式上。不报错、不白屏,一眼就能认出来。
控制器传进来的变量
| 键 | 来源 | 是什么 |
|---|---|---|
__content | View.php:65,69 引擎注入 | string。子视图渲染好的完整 HTML,echo 时不要再转义 |
page | FC 各方法硬编码 | string,比如 index、sort、site。用来出 body 的 class |
site | 仅站点详情页,FC:202 | dtr_list 单行或不存在。layout 只读它推标题 |
sort | 分类页、详情页 | dtr_sort 单行或不存在 |
article | 文章详情页 | dtr_wz 单行,layout 只用 title 和 keywords |
kw | 搜索页 FC:221 | string,用户输入的关键词原文 |
topic | 专题页 | dtr_zt 行,用 name 和 description |
seo_title | 插件页才给 | string。给了就完全接管 title,不再走推导链 |
conf / app | index.php:21-23 全局共享 | 两个数组,所有视图都能看到 |
这一页挂的钩子
| 钩子名 | 触发位置 | 典型用途 |
|---|---|---|
front_head | layout.php:84 | 给 head 里插 meta、样式、脚本,插件统计代码就挂这里 |
front_body_start | layout.php:87 | body 刚打开,适合挂全站横幅、客服码 |
front_slot_head | layout.php:92 | 页头下方的通栏广告位 |
front_body_end | layout.php:104 | body 收尾前,插脚本的地方 |
容易踩的地方
- 第 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。
控制器传进来的变量
| 键 | 来源 | 是什么 |
|---|---|---|
page | layout:91 传入 | string。注意:默认模板的 header 代码其实没读它,只有注释里提 |
navs | 本页现查 Nav::ordered(),header.php:9 | dtr_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_extra | header.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。
控制器传进来的变量
| 键 | 来源 | 是什么 |
|---|---|---|
page | layout:99 传入 | string,本页代码不读 |
footLinks | 本页解析 tplcfg("foot_link") | 二维数组,每项 [名称, 地址],来自每行「名称,地址」的 explode |
disclaimer | tplcfg("foot_disclaimer") | string |
footAd | Config::get("ad_footer") | string,HTML 原文,只有 ad_enable 为 1 才输出 |
conf / app | 全局共享 | 数组 |
这一页挂的钩子
| 钩子名 | 触发位置 | 典型用途 |
|---|---|---|
front_footer_extra | footer.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')); ?> © <?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。
控制器传进来的变量
| 键 | 来源 | 是什么 |
|---|---|---|
sorts | Sort::ordered() | dtr_sort 行列表,全列 |
recommend | Site::recommend(16) | dtr_list 行列表,条件 is_tui = 1 按 id 排 |
latest | Site::latest(12) | dtr_list 行列表,status=1 按 created_at DESC |
topView | Site::topView(10) | dtr_list 行列表,按 view DESC |
recent | Site::recentHits(20) | dtr_list 行列表,条件 status=1 AND last_hit > 0,按 last_hit DESC |
notice | Notice::latest(5) | dtr_notice 行列表:id, content, created_at |
links | Link::ordered() | dtr_link 行列表:id, name, url,按 id 排 |
articles | Article::latest(8) | dtr_wz 行列表,VISIBLE 条件,按 publish_at DESC |
cntList | Site::count(status = 1) | int,已收录站点数 |
cntWz | Article::countLive() | int,可见文章数 |
cntSort | Sort::count(1) | int,分类总数 |
cntApply | Apply::pendingCount() | int,待审提交数。注意统计页那个同名键是全部提交数,口径不一样 |
这一页挂的钩子
| 钩子名 | 触发位置 | 典型用途 |
|---|---|---|
front_index | FC: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。