HTTP头部转换机制详解
在php环境中，当我们通过$_server超全局变量访问http请求头部时，会发现自定义的头部名称与客户端发送时有所不同。例如，客户端发送的x-auth-hmac头部，在php中可能显示为http_x_auth_hmac。这种现象并非偶然，而是遵循了cgi 1.1规范（rfc 3875）中的明确规定。
根据RFC 3875的第4.1.18节，关于“Meta-variables with names beginning with HTTP_”的描述，HTTP头部字段名称会被转换成元变量名，具体规则如下：
- 转换为大写： 原始HTTP头部名称中的所有字符都会被转换为大写。
- 连字符替换： 头部名称中的所有连字符（-）都会被替换为下划线（_）。
- 添加前缀： 最终转换后的名称前会统一添加HTTP_前缀。
因此，一个名为X-Auth-HMAC的HTTP头部，经过上述规则转换后，在$_SERVER中就会以HTTP_X_AUTH_HMAC的形式出现。
客户端发送自定义头部示例
为了更好地理解这一机制，我们首先看一个Java客户端如何发送自定义HTTP头部的示例。这里使用Java 11+的HttpClient：
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.concurrent.CompletableFuture;
public class HttpClientExample {
public static void main(String[] args) {
HttpClient client = HttpClient.newBuilder().build();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("http://php-fpm:80/index.php")) // 替换为你的PHP服务地址
.header("Content-Type", "application/json")
.header("X-Auth-HMAC", "test_hmac_header_value") // 自定义头部
.POST(HttpRequest.BodyPublishers.ofString("{\"message\": \"hello from Java\"}"))
.build();
CompletableFuture> responseFuture = client.sendAsync(request, HttpResponse.BodyHandlers.ofString());
responseFuture.thenApply(HttpResponse::body)
.thenAccept(System.out::println)
.join(); // 等待异步操作完成
}
} 上述代码中，我们明确发送了一个名为X-Auth-HMAC的自定义头部，其值为test_hmac_header_value。
立即学习“PHP免费学习笔记（深入）”；
PHP服务端获取转换后的头部
在PHP服务端，获取客户端发送的HTTP头部主要有两种方式：通过$_SERVER超全局变量或使用getallheaders()函数。
1. 使用 $_SERVER 超全局变量
$_SERVER变量包含了由Web服务器提供的大量信息，其中包括经过CGI规范转换后的HTTP头部。要获取X-Auth-HMAC头部，我们需要查找HTTP_X_AUTH_HMAC：
'success',
'received_headers' => [],
'raw_post_data' => file_get_contents('php://input')
];
// 尝试从 $_SERVER 获取转换后的头部
if (isset($_SERVER['HTTP_X_AUTH_HMAC'])) {
$response['received_headers']['X-Auth-HMAC_from_SERVER'] = $_SERVER['HTTP_X_AUTH_HMAC'];
} else {
$response['received_headers']['X-Auth-HMAC_from_SERVER'] = 'Not Found in $_SERVER (HTTP_X_AUTH_HMAC)';
}
// 输出 $_SERVER 中所有以 HTTP_ 开头的头部，以供调试
foreach ($_SERVER as $key => $value) {
if (str_starts_with($key, 'HTTP_')) {
$originalHeaderName = str_replace('_', '-', substr($key, 5));
$response['received_headers']['_SERVER_RAW'][$key] = $value;
// 尝试还原原始头部名称（仅为演示）
$response['received_headers']['_SERVER_MAPPED'][strtolower($originalHeaderName)] = $value;
}
}
echo json_encode($response, JSON_PRETTY_PRINT);
?>运行上述PHP脚本并用Java客户端发送请求后，你将在PHP的输出中看到类似以下内容：
{
"status": "success",
"received_headers": {
"X-Auth-HMAC_from_SERVER": "test_hmac_header_value",
"_SERVER_RAW": {
"HTTP_HOST": "php-fpm:80",
"HTTP_CONTENT_TYPE": "application/json",
"HTTP_X_AUTH_HMAC": "test_hmac_header_value",
// ... 其他HTTP_开头的头部
},
"_SERVER_MAPPED": {
"host": "php-fpm:80",
"content-type": "application/json",
"x-auth-hmac": "test_hmac_header_value"
}
},
"raw_post_data": "{\"message\": \"hello from Java\"}"
}2. 使用 getallheaders() 函数
getallheaders()函数提供了一种更直接、更接近原始HTTP头部名称的方式来获取所有请求头部。这个函数返回一个关联数组，其中键是原始的HTTP头部名称（通常是首字母大写，连字符分隔），值是对应头部的内容。
'success',
'received_headers' => [],
'raw_post_data' => file_get_contents('php://input')
];
// 使用 getallheaders() 获取所有头部
if (function_exists('getallheaders')) {
$allHeaders = getallheaders();
$response['received_headers']['all_headers_from_getallheaders'] = $allHeaders;
// 检查 X-Auth-HMAC 头部
if (isset($allHeaders['X-Auth-HMAC'])) {
$response['received_headers']['X-Auth-HMAC_from_getallheaders'] = $allHeaders['X-Auth-HMAC'];
} else {
$response['received_headers']['X-Auth-HMAC_from_getallheaders'] = 'Not Found in getallheaders()';
}
} else {
$response['received_headers']['getallheaders_status'] = 'getallheaders() function is not available.';
}
echo json_encode($response, JSON_PRETTY_PRINT);
?>使用getallheaders()时，你将能直接通过$allHeaders['X-Auth-HMAC']访问到头部，而无需进行名称转换的考虑。这个函数在Apache和Nginx (通过PHP-FPM) 环境下通常可用，但在某些非标准或嵌入式PHP环境中可能不存在。
注意事项
- 命名规范一致性： 尽管PHP会自动转换头部名称，但在客户端发送时，建议遵循HTTP头部命名规范（如使用连字符分隔单词，如X-Custom-Header）。这有助于提高可读性和跨平台兼容性。
- getallheaders()的可用性： getallheaders()函数在不同的PHP运行环境中可能存在差异。它通常在作为Apache模块或通过PHP-FPM运行时可用，但在CLI或某些特殊SAPI（Server API）下可能不可用。因此，如果需要最大兼容性，同时检查$_SERVER和getallheaders()是一种稳妥的做法。
- Web服务器配置： Web服务器（如Nginx、Apache）在将请求传递给PHP-FPM时，会处理HTTP头部。它们会确保这些头部按照CGI规范被正确地传递给PHP脚本。某些Web服务器配置（例如Nginx中的underscores_in_headers指令）可能会影响包含下划线的头部处理，但对于标准连字符分隔的头部，通常不会有问题。
- 安全性考量： 无论是通过$_SERVER还是getallheaders()获取的头部信息，都直接来源于客户端请求。在处理敏感信息（如认证令牌）时，务必进行严格的验证、过滤和消毒，以防范潜在的安全漏洞，如注入攻击或伪造请求。
总结
PHP中HTTP头部名称的自动转换是基于CGI 1.1规范的标准化行为。当客户端发送如X-Auth-HMAC这样的自定义头部时，PHP通过$_SERVER超全局变量接收到的将是HTTP_X_AUTH_HMAC。开发者可以通过理解这一转换规则，在$_SERVER中正确查找对应的头部信息。此外，getallheaders()函数提供了一个更直观的获取所有头部的方式，它返回的键名更接近原始HTTP头部名称，但在使用时需注意其环境兼容性。掌握这些机制对于开发健壮和可维护的PHP应用程序至关重要。
