<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="context.http" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" annotations="verify_info:false" role="stream_context_option">

<refnamediv>

<refname>HTTP context 选项</refname>

<refpurpose>HTTP context 的选项列表</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<para>

提供给 <literal>http://</literal> 和 <literal>https://</literal> 传输协议的 context 选项。

transports.

</para>

</refsect1>

<refsect1 role="options"><!-- {{{ -->

&reftitle.options;

<para>

<variablelist>

<varlistentry xml:id="context.http.method">

<term>

<parameter>method</parameter>

<type>string</type>

</term>

<listitem>

<para>

远程服务器支持的 <constant>GET</constant>，<constant>POST</constant> 或其它 HTTP 方法。

</para>

<para>

默认值是 <constant>GET</constant>。

</para>

</listitem>

</varlistentry>

<varlistentry xml:id="context.http.header">

<term>

<parameter>header</parameter>

<type>array</type> 或 <type>string</type>

</term>

<listitem>

<para>

请求期间发送的附加 header 。此选项中的值将覆盖其他值

（如 <literal>User-agent:</literal>， <literal>Host:</literal> 和

<literal>Authentication:</literal>)，

即使在执行 <literal>Location:</literal> 重定向时也是如此。

所以，如果启用了 <parameter>follow_location</parameter>

就不建议设置 <literal>Host:</literal> header。

</para>

<para>

字符串值是以 <literal>\r\n</literal> 分隔的 <literal>Key: value</literal>，例如 <literal>"Content-Type:

application/json\r\nConnection: close"</literal>。数组值应为 <literal>Key: value</literal>

的列表，例如 <literal>["Content-Type: application/json", "Connection: close"]</literal>。

</para>

</listitem>

</varlistentry>

<varlistentry xml:id="context.http.user-agent">

<term>

<parameter>user_agent</parameter>

<type>string</type>

</term>

<listitem>

<para>

要发送的 header <literal>User-Agent:</literal> 的值。如果在上面的

<literal>header</literal> context 选项中没有指定 user-agent，此值将被使用。

</para>

<para>

默认使用 &php.ini; 中设置的 <link linkend="ini.user-agent">user_agent</link>。

</para>

</listitem>

</varlistentry>

<varlistentry xml:id="context.http.content">

<term>

<parameter>content</parameter>

<type>string</type>

</term>

<listitem>

<para>

在 header 后面要发送的额外数据。通常使用POST或PUT请求。

</para>

</listitem>

</varlistentry>

<varlistentry xml:id="context.http.proxy">

<term>

<parameter>proxy</parameter>

<type>string</type>

</term>

<listitem>

<para>

URI 指定的代理服务器的地址（例如：

<literal>tcp://proxy.example.com:5100</literal>）。

</para>

</listitem>

</varlistentry>

<varlistentry xml:id="context.http.request-fulluri">

<term>

<parameter>request_fulluri</parameter>

<type>bool</type>

</term>

<listitem>

<para>

当设置为 &true; 时，在构建请求时将使用整个 URI（例如：

<literal>GET http://www.example.com/path/to/file.html HTTP/1.0</literal>）。

虽然这是一个非标准的请求格式，但某些代理服务器需要它。

</para>

<para>

默认值是 &false;.

</para>

</listitem>

</varlistentry>

<varlistentry xml:id="context.http.follow-location">

<term>

<parameter>follow_location</parameter>

<type>int</type>

</term>

<listitem>

<para>

跟随 <literal>Location</literal> header 的重定向。设置为 <literal>0</literal> 以禁用。

</para>

<para>

默认值是 <literal>1</literal>。

</para>

</listitem>

</varlistentry>

<varlistentry xml:id="context.http.max-redirects">

<term>

<parameter>max_redirects</parameter>

<type>int</type>

</term>

<listitem>

<para>

跟随重定向的最大次数。值为 <literal>1</literal> 或更少则意味不跟随重定向。

</para>

<para>

默认值是 <literal>20</literal>。

</para>

</listitem>

</varlistentry>

<varlistentry xml:id="context.http.protocol-version">

<term>

<parameter>protocol_version</parameter>

<type>float</type>

</term>

<listitem>

<para>

HTTP 协议版本。

</para>

<para>

PHP 8.0.0 起默认值是 <literal>1.1</literal>。在此之前默认值是 <literal>1.0</literal>。

</para>

</listitem>

</varlistentry>

<varlistentry xml:id="context.http.timeout">

<term>

<parameter>timeout</parameter>

<type>float</type>

</term>

<listitem>

<para>

读取超时时间，单位为秒（s），用 <type>float</type> 指定（例如：<literal>10.5</literal>）。

</para>

<para>

默认使用 &php.ini; 中设置的 <link linkend="ini.default-socket-timeout">default_socket_timeout</link>。

</para>

</listitem>

</varlistentry>

<varlistentry xml:id="context.http.ignore-errors">

<term>

<parameter>ignore_errors</parameter>

<type>bool</type>

</term>

<listitem>

<para>

即使是故障状态码依然获取内容。

</para>

<para>

默认值为 &false;.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1><!-- }}} -->

<refsect1 role="examples"><!-- {{{ -->

&reftitle.examples;

<para>

<example xml:id="context.http.example-post"><!-- {{{ -->

<title>获取一个页面并发送 POST 数据</title>

<programlisting role="php">

</programlisting>

</example><!-- }}} -->

</para>

<para>

<example xml:id="context.http.example-fetch-ignore-redirect"><!-- {{{ -->

<title>忽略重定向并获取 header 和内容</title>

<programlisting role="php">

</programlisting>

</example><!-- }}} -->

</para>

</refsect1><!-- }}} -->

<refsect1 role="notes">

&reftitle.notes;

<note>

<title>底层 socket stream 上下文选项</title>

<simpara>

Additional context options may be supported by the

<link linkend="transports.inet">underlying transport</link>

For <literal>http://</literal> streams, refer to context

options for the <literal>tcp://</literal> transport. For

<literal>https://</literal> streams, refer to context options

for the <literal>ssl://</literal> transport.

</simpara>

</note>

<note>

<title>HTTP 状态行</title>

<simpara>

When this stream wrapper follows a redirect, the

<literal>wrapper_data</literal> returned by

<function>stream_get_meta_data</function> might not necessarily contain

the HTTP status line that actually applies to the content data at index

<literal>0</literal>.

</simpara>

<screen>

</screen>

<simpara>

第一个请求返回 <literal>301</literal> （永久重定向），

因此 stream 包装器自动跟随重定向到获得 <literal>200</literal>

响应（index = <literal>4</literal>）。

</simpara>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><xref linkend="wrappers.http" /></member>

<member><xref linkend="context.socket" /></member>

<member><xref linkend="context.ssl" /></member>

</simplelist>

</para>

</refsect1>

</refentry>