PHP上下文选项和参数

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 开始可用。

五、Phar上下文选项

• Phar 上下文（context）选项 — Phar 上下文（context）选项列表。
• phar:// 封装（wrapper）的上下文（context）选项。

1、可选项

• compress int：Phar 压缩常量中的一个。
• metadata mixed：Phar 元数据（metadata）。查看 Phar::setMetadata()。

六、Context参数

• Context 参数 — Context 参数列表
• 这些参数（parameters）可以设置为由函数 stream_context_set_params() 返回的 context。
• notification callable：当一个流（stream）上发生事件时，callable 将被调用。

七、Zip上下文选项

• Zip 上下文选项 — Zip 上下文选项列表
• Zip 上下文选项可用于 zip 包装器。
• password：用于指定加密归档的密码。

八、Zlib上下文选项

• Zlib 上下文选项 — Zlib 上下文选项列表
• Zlib 上下文选项可用于 zlib 封装协议。
• level：用于指定压缩级别（0 - 9）。