PHP插件开发中的一个错误：JSON直接输出导致网站首页异常
问题描述
最近在使用步数统计插件（WeFootStep）时，发现网站首页完全变成了一段JSON数据，而不是正常的HTML页面。具体表现为首页显示如下内容：
{"results":"<li><a href=\"https:\/\/blog.ybyq.wang\/archives\/186.html\">\u770b\u770b\u4f60\u662f\u4e0d\u662f\u201c\u8d5e\u535a\u6587\u76f2\u201d<p class=\"text-muted\">dobe\u3001IDEA\u3001<mark class='text_match'>pycharm<\/mark>\u7b49\r\n<\/p><\/a><\/li>..."}
这完全破坏了网站的正常浏览体验。
原因分析
经过几天的艰苦排查，发现问题出在WeFootStep插件的Widget.php文件中的getStepDataJson()函数：
/*** 获取步数JSON数据，用于AJAX请求*/
public function getStepDataJson()
{$history = $this->getStepHistory();$stats = $this->getStepStats();$data = ['history' => $history,'stats' => $stats];header('Content-Type: application/json');echo json_encode($data);exit;
}
这个函数存在的问题是：
- 函数直接设置了响应头为
application/json - 输出JSON编码后的数据
- 调用
exit终止了PHP的执行流程
这种实现方式本来是为AJAX请求设计的，但如果在普通页面加载过程中被误调用，就会导致整个页面只输出JSON数据。
解决方案
解决方案很简单：修改getStepDataJson()函数，让它只在确认是AJAX请求时才直接输出JSON并退出：
/*** 获取步数JSON数据，用于AJAX请求*/
public function getStepDataJson()
{$history = $this->getStepHistory();$stats = $this->getStepStats();$data = ['history' => $history,'stats' => $stats];// 只在AJAX请求时才直接输出JSON并退出if (!empty($_SERVER['HTTP_X_REQUESTED_WITH']) && strtolower($_SERVER['HTTP_X_REQUESTED_WITH']) == 'xmlhttprequest') {header('Content-Type: application/json');echo json_encode($data);exit;}// 如果不是AJAX请求，返回数据而不直接输出return $data;
}
这个改进添加了一个检查机制，通过判断$_SERVER['HTTP_X_REQUESTED_WITH']是否为xmlhttprequest来确定当前是否是一个AJAX请求。如果是，才执行原来的行为；如果不是，则只返回数据而不直接输出。
技术要点
-
AJAX请求的识别：通常AJAX请求会包含
X-Requested-With: XMLHttpRequest头，这是检测AJAX请求的标准方法。 -
避免直接输出：在MVC架构的应用中，控制器方法通常不应该直接输出内容，而是返回数据让框架处理。
-
避免无条件退出：
exit或die会立即终止PHP的执行，应谨慎使用，尤其是在可能被其他代码调用的函数中。
教训与最佳实践
在开发PHP插件或组件时，应遵循以下原则：
-
关注点分离：数据处理与输出应该分开，不要在获取数据的函数中直接输出。
-
条件性输出：如果必须在函数中输出，应该有明确的条件控制。
-
防御性编程：总是假设你的函数可能在意外的情况下被调用，添加适当的检查。
-
明确文档：清晰记录函数的行为和副作用，特别是那些会改变HTTP头或直接输出的函数。
这个简单的修改解决了首页显示JSON数据的问题，也提醒我们在插件开发中要注意代码的健壮性和兼容性。
作者：xuan
个人博客：https://blog.ybyq.wang
原文链接：https://blog.ybyq.wang/archives/770.html
欢迎访问我的博客，获取更多技术文章和教程。