PHP上下文选项和参数

2024-01-09 32

PHP提供了丰富的上下文选项和参数，可以用于所有文件系统或数据流封装协议。上下文（Context）是通过stream_context_create()函数创建的，在此过程中可以指定一些选项和参数。选项可以使用stream_context_set_option()函数进行设置，而参数则可以使用stream_context_set_params()函数进行设置。

一、套接字上下文选项

套接字上下文选项 — 套接字上下文选项列表。套接字上下文选项可用于所有工作在套接字上的封装协议，像 tcp, http 和 ftp。

1、可选项

bindto：用户 PHP 访问网络的指定的 IP 地址（IPv4 或 IPv6 其中的一个）和/或端口号，这个语法是 ip:port。设置 IP 或者 port 为 0 将会让系统选择 IP 或 port。由于 FTP 在正常操作时会创建两个 socket 连接，因此无法使用此选项指定端口号。

backlog：用于限制 socket 监听队列中未完成连接的数量。仅适用于 stream_socket_server()。
ipv6_v6only：覆盖有关 IPv4 映射到 IPv6 的操作系统默认值。在 [::] 上存在绑定的时候，当尝试在各自的 Ipv4 地址上监听，这是尤其重要。这仅适用于 stream_socket_server()。
so_reuseport：即使来自不同的进程，也能对同一个 ip:port 对进行多个绑定。这仅适用于 stream_socket_server()。
so_broadcast：允许向广播地址发送数据，从广播地址接收数据。这仅适用于 stream_socket_server()。
tcp_nodelay：设置此选项为 true 将相应地设置 SOL_TCP,NO_DELAY=1，从而禁用 TCP Nagle 算法。

二、HTTP context选项

HTTP context 选项 — HTTP context 的选项列表。提供给 http:// 和 https:// 传输协议的 context 选项。

1、可选项

method string：远程服务器支持的 GET，POST 或其它 HTTP 方法。默认值是 GET。
header array 或 string：请求期间发送的附加 header 。此选项中的值将覆盖其他值（如 User-agent:， Host: 和 Authentication:)，即使在执行 Location: 重定向时也是如此。所以，如果启用了 follow_location 就不建议设置 Host: header。
user_agent string：要发送的 header User-Agent: 的值。如果在上面的 header context 选项中没有指定 user-agent，此值将被使用。默认使用 php.ini 中设置的 user_agent。
content string：在 header 后面要发送的额外数据。通常使用POST或PUT请求。
proxy string：URI 指定的代理服务器的地址。(e.g. tcp://proxy.example.com:5100).
request_fulluri bool：当设置为 true 时，在构建请求时将使用整个 URI 。(例如： GET http://www.example.com/path/to/file.html HTTP/1.0)。虽然这是一个非标准的请求格式，但某些代理服务器需要它。默认值是 false.
follow_location int：跟随 Location header 的重定向。设置为 0 以禁用。默认值是 1。
max_redirects int：跟随重定向的最大次数。值为 1 或更少则意味不跟随重定向。默认值是 20。
protocol_version float：HTTP 协议版本。
PHP 8.0.0 起默认值是 1.1。在此之前默认值是 1.0。
timeout float：读取超时时间，单位为秒（s），用 float 指定(e.g. 10.5)。默认使用 php.ini 中设置的 default_socket_timeout。
ignore_errors bool：即使是故障状态码依然获取内容。默认值为 false.

2、示例

获取一个页面并发送 POST 数据：

<?php
$postdata = http_build_query(
array(
'var1' => 'some content',
'var2' => 'doh'
)
);
$opts = array('http' =>
array(
'method' => 'POST',
'header' => 'Content-type: application/x-www-form-urlencoded',
'content' => $postdata
)
);
$context = stream_context_create($opts);
$result = file_get_contents('http://example.com/submit.php', false, $context);
?>

忽略重定向并获取 header 和内容：

<?php
$url = "http://www.example.org/header.php";
$opts = array('http' =>
array(
'method' => 'GET',
'max_redirects' => '0',
'ignore_errors' => '1'
)
);
$context = stream_context_create($opts);
$stream = fopen($url, 'r', false, $context);
// header 信息和 stream 的元数据一样
var_dump(stream_get_meta_data($stream));
// $url 的实际数据
var_dump(stream_get_contents($stream));
fclose($stream);
?>

3、注释

底层传输可能支持其他上下文选项对于 http:// 流，请参阅 tcp:// 传输的上下文选项。对于 https:// 流，请参阅 ssl:// 传输的上下文选项。

当该流包装器跟随重定向时，stream_get_meta_data() 返回的 wrapper_data 可能不一定包含实际适用于索引 0 处内容数据的 HTTP 状态行。

array (
'wrapper_data' =>
array (
0 => 'HTTP/1.0 301 Moved Permanently',
1 => 'Cache-Control: no-cache',
2 => 'Connection: close',
3 => 'Location: http://example.com/foo.jpg',
4 => 'HTTP/1.1 200 OK',
...

第一个请求返回 301 （永久重定向），因此 stream 包装器自动跟随重定向到获得 200 响应（index = 4）。

三、FTP上下文选项

FTP 上下文选项 — FTP 上下文选项列表。

ftp:// 和 ftps:// 传输的上下文选项。

1、可选项

overwrite bool：允许覆盖远程服务器上已有的文件。仅适用于写入模式（上传）。默认为 false。
resume_pos int：开始传输的文件偏移量。仅适用于读取模式（下载）。默认为 0 （文件开头）。
proxy string：通过 http 代理服务器代理 FTP 请求。仅适用于文件读取操作。例如：tcp://squid.example.com:8000。

2、注释

底层传输可能支持其他上下文选项对于 ftp:// 流，请参阅 tcp:// 传输的上下文选项。对于 ftps:// 流，请参阅 ssl:// 传输的上下文选项。

四、SSL上下文选项

SSL 上下文选项 — SSL 上下文选项清单。
ssl:// 和 tls:// 传输协议上下文选项清单。

1、可选项

peer_name string：要连接的服务器名称。如果未设置，那么服务器名称将根据打开 SSL 流的主机名称猜测得出。
verify_peer bool：是否需要验证 SSL 证书。默认值为 true。
verify_peer_name bool：是否需要验证 peer name。默认值为 true.
allow_self_signed bool：是否允许自签名证书。需要配合 verify_peer 参数使用（注：当 verify_peer 参数为 true 时才会根据 allow_self_signed 参数值来决定是否允许自签名证书）。默认值为 false
cafile string：当设置 verify_peer 为 true 时，用来验证远端证书所用到的 CA 证书。本选项值为 CA 证书在本地文件系统的全路径及文件名。
capath string：如果未设置 cafile，或者 cafile 所指的文件不存在时，会在 capath 所指定的目录搜索适用的证书。该目录必须是已经经过哈希处理的证书目录。（注：所谓 hashed certificate 目录是指使用类似 c_rehash 命令将目录中的 .pem 和 .crt 文件扫描并提取哈希码，然后根据此哈希码创建文件链接，以便于快速查找证书）
local_cert string：文件系统上的本地证书路径。必须是 PEM 编码的文件，包含证书及私钥。也可以包含证书颁发者证书链。也可以通过 local_pk 指定包含私钥的独立文件。
local_pk string：如果使用独立的文件来存储证书（local_cert）和私钥，那么使用此选项来指明私钥文件的路径。
passphrase string：local_cert 文件的密码。
verify_depth int：如果证书链条层次太深，超过了本选项的设定值，则终止验证。默认情况下不限制证书链条层次深度。
ciphers string：设置可用的密码列表。
capture_peer_cert bool：如果设置为 true 将会在上下文中创建 peer_certificate 选项，该选项中包含远端证书。
capture_peer_cert_chain bool：如果设置为 true 将会在上下文中创建 peer_certificate_chain 选项，该选项中包含远端证书链条。
SNI_enabled bool：设置为 true 将启用服务器名称指示（server name indication）。启用 SNI 将允许同一 IP 地址使用多个证书。
disable_compression bool：如果设置，则禁用 TLS 压缩，有助于减轻恶意攻击。
peer_fingerprint string | array：当远程服务器证书的摘要和指定的散列值不相同的时候，终止操作。当使用 string 时，会根据字符串的长度来检测所使用的散列算法：“md5”（32 字节）还是“sha1”（40 字节）。当使用 array 时，数组的键表示散列算法名称，其对应的值是预期的摘要值。
security_level int：设置安全级别。如果未指定，则使用库默认安全级别。安全级别说明请参考 » SSL_CTX_get_security_level(3)。从 PHP 7.2.0 和 OpenSSL 1.1.0 开始可用。