sigmasternchen/php-doc-en
1
0
Fork 0
mirror of https://github.com/sigmasternchen/php-doc-en synced 2025-03-15 16:38:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

- Refactor stream context options and stream context parameters

Browse source 
- Document the curl context options


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@257496 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Hannes Magnusson 2008-04-14 17:24:12 +00:00
parent 80e1b05b48
commit 71a0e2144a
9 changed files with 1150 additions and 374 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

126
appendices/transports.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.16 $ -->
<!-- $Revision: 1.17 $ -->
<appendix xml:id="transports" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>List of Supported Socket Transports</title>
<para>
@ -88,130 +88,6 @@
<literal>sslv3://</literal> will select the SSL V2 or SSL V3
protocol explicitly.
</simpara>
<para>
<table>
<title>
Context options for <literal>ssl://</literal> and <literal>tls://</literal>
transports (since PHP 4.3.2)
</title>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Usage</entry>
<entry>Default</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>verify_peer</literal></entry>
<entry>
&true; or &false;.
Require verification of SSL certificate used.
</entry>
<entry>&false;</entry>
</row>
<row>
<entry><literal>allow_self_signed</literal></entry>
<entry>
&true; or &false;.
Allow self-signed certificates.
</entry>
<entry>&false;</entry>
</row>
<row>
<entry><literal>cafile</literal></entry>
<entry>
Location of Certificate Authority file on local filesystem
which should be used with the <literal>verify_peer</literal>
context option to authenticate the identity of the remote peer.
</entry>
<entry></entry>
</row>
<row>
<entry><literal>capath</literal></entry>
<entry>
If <literal>cafile</literal> is not specified or if the certificate
is not found there, the directory pointed to by <literal>capath</literal>
is searched for a suitable certificate. <literal>capath</literal>
must be a correctly hashed certificate directory.
</entry>
<entry></entry>
</row>
<row>
<entry><literal>local_cert</literal></entry>
<entry>
Path to local certificate file on filesystem. It must be a PEM
encoded file which contains your certificate and private key.
It can optionally contain the certificate chain of issuers.
</entry>
<entry></entry>
</row>
<row>
<entry><literal>passphrase</literal></entry>
<entry>
Passphrase with which your <literal>local_cert</literal> file
was encoded.
</entry>
<entry></entry>
</row>
<row>
<entry><literal>CN_match</literal></entry>
<entry>
Common Name we are expecting. PHP will perform limited wildcard
matching. If the Common Name does not match this, the connection
attempt will fail.
</entry>
<entry></entry>
</row>
<row>
<entry><literal>verify_depth</literal></entry>
<entry>
Abort if the certificate chain is too deep.
</entry>
<entry></entry>
</row>
<row>
<entry><literal>ciphers</literal></entry>
<entry>
Sets the list of available ciphers. The format of the string is described
in <link xlink:href="&url.openssl.ciphers;">ciphers(1)</link>. Added
in PHP 5.0.0.
</entry>
<entry><literal>DEFAULT</literal></entry>
</row>
<row>
<entry><literal>capture_peer_cert</literal></entry>
<entry>
If set to &true; a <literal>peer_certificate</literal> context option
will be created containing the peer certificate. Added in PHP 5.0.0.
</entry>
<entry>&false;</entry>
</row>
<row>
<entry><literal>capture_peer_cert_chain</literal></entry>
<entry>
If set to &true; a <literal>peer_certificate_chain</literal> context
option will be created containing the certificate chain. Added in PHP
5.0.0.
</entry>
<entry>&false;</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<simpara>
Because <literal>ssl://</literal> is the underlying transport for the
<link linkend="wrappers.http"><literal>https://</literal></link> and
<link linkend="wrappers.ftp"><literal>ftps://</literal></link> wrappers,
any context options which apply to <literal>ssl://</literal> also apply to
<literal>https://</literal> and <literal>ftps://</literal>.
</simpara>
</note>
</section>
<section xml:id="transports.unix">

250
appendices/wrappers.xml
View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.78 $ -->
<!-- $Revision: 1.79 $ -->
<appendix xml:id="wrappers" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>List of Supported Protocols/Wrappers</title>
<para>
@ -95,59 +95,6 @@
</para>
</section>
<section xml:id="wrappers.socket">
<title>Socket</title>
<para>
This section contains the context options supported by the wrappers that
work over sockets, like <literal>tcp</literal>, <literal>http</literal> or
<literal>ftp</literal>.
</para>
<para>
As of PHP 5.1.0 only one option is supported, <literal>bindto</literal>,
which can be used to specify the IP address (either IPv4 or IPv6) and/or
the port number that PHP will use to access the network. The syntax is
<literal>ip:port</literal> (you can set the IP or the port number to
<literal>0</literal> if you want to let the system choose them for you).
</para>
<note>
<para>
As FTP creates two socket connections during normal operation, you cannot
specify the port number in the <literal>bindto</literal> option. So, the
only supported syntax is <literal>ip:0</literal> for the FTP wrapper.
</para>
</note>
<example>
<title>Some examples of how to use the bindto option</title>
<programlisting role="php">
<![CDATA[
<?php
// connect to the internet using the '192.168.0.100' IP
$opts = array('socket' =>
array('bindto' => '192.168.0.100:0'));
// connect to the internet using the '192.168.0.100' IP and port '7000'
$opts = array('socket' =>
array('bindto' => '192.168.0.100:7000'));
// connect to the internet using port '7000'
$opts = array('socket' =>
array('bindto' => '0:7000'));
// create the context...
$context = stream_context_create($opts);
// ...and use it to fetch the data
echo file_get_contents('http://www.example.com', false, $context);
?>
]]>
</programlisting>
</example>
</section>
<section xml:id="wrappers.http">
<title>HTTP and HTTPS</title>
<simpara>PHP 4, PHP 5, PHP 6. <filename>https://</filename> since PHP 4.3.0</simpara>
@ -202,35 +149,6 @@ foreach($meta_data['wrapper_data'] as $response) {
]]>
</programlisting>
</informalexample>
<example>
<title>Fetch a page and send POST data</title>
<programlisting role="php">
<![CDATA[
<?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);
?>
]]>
</programlisting>
</example>
<simpara>
The stream allows access to the <emphasis>body</emphasis> of
the resource; the headers are stored in the
@ -302,120 +220,6 @@ $result = file_get_contents('http://example.com/submit.php', false, $context);
</tgroup>
</table>
</para>
<para>
<table>
<title>Context options</title>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Usage</entry>
<entry>Default</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>method</literal></entry>
<entry>
<constant>GET</constant>, <constant>POST</constant>, or
any other HTTP method supported by the remote server.
</entry>
<entry><constant>GET</constant></entry>
</row>
<row>
<entry><literal>header</literal></entry>
<entry>Additional headers to be sent during request. Values
in this option will override other values (such as
<literal>User-agent:</literal>, <literal>Host:</literal>,
and <literal>Authentication:</literal>).
</entry>
<entry></entry>
</row>
<row>
<entry><literal>user_agent</literal></entry>
<entry>Value to send with User-Agent: header. This value will
only be used if user-agent is <emphasis>not</emphasis> specified
in the <literal>header</literal> context option above.
</entry>
<entry>
&php.ini; setting: <literal>user_agent</literal>
</entry>
</row>
<row>
<entry><literal>content</literal></entry>
<entry>
Additional data to be sent after the headers. Typically used
with POST or PUT requests.
</entry>
<entry></entry>
</row>
<row>
<entry><literal>proxy</literal></entry>
<entry>
URI specifying address of proxy server. (e.g.
<literal>tcp://proxy.example.com:5100</literal>). HTTPS proxying
(through HTTP proxies) only works in PHP 5.1.0 or greater.
</entry>
<entry></entry>
</row>
<row>
<entry><literal>request_fulluri</literal></entry>
<entry>
When set to &true;, the entire URI will be used when
constructing the request. (i.e.
<literal>GET http://www.example.com/path/to/file.html HTTP/1.0</literal>).
While this is a non-standard request format, some
proxy servers require it.
</entry>
<entry>&false;</entry>
</row>
<row>
<entry><literal>max_redirects</literal></entry>
<entry>
The max number of redirects to follow. Value <literal>1</literal> or
less means that no redirects are followed.
Added in PHP 5.1.0.
</entry>
<entry>20</entry>
</row>
<row>
<entry><literal>protocol_version</literal></entry>
<entry>
HTTP protocol version. Added in PHP 5.1.0.
</entry>
<entry>1.0</entry>
</row>
<row>
<entry><literal>timeout</literal></entry>
<entry>
Read timeout in seconds, specified by a <type>float</type> (e.g.
<literal>10.5</literal>). Added in PHP 5.2.1.
</entry>
<entry><link linkend="ini.default-socket-timeout">default_socket_timeout</link></entry>
</row>
<row>
<entry><literal>ignore_errors</literal></entry>
<entry>
Fetch the content even on failure status codes. Added in PHP 5.3.0.
</entry>
<entry>&false;</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<title>Underlying socket stream context options</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>
<para>
Custom headers may be sent with an HTTP request prior to
@ -569,58 +373,6 @@ X-MyCustomHeader: Foo
</tgroup>
</table>
</para>
<para>
<table>
<title>Context options (as of PHP 5.0.0)</title>
<tgroup cols="3">
<thead>
<row>
<entry>Name</entry>
<entry>Usage</entry>
<entry>Default</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>overwrite</literal></entry>
<entry>
Allow overwriting of already existing files on remote server.
Applies to write mode (uploading) only.
</entry>
<entry>&false; (Disabled)</entry>
</row>
<row>
<entry><literal>resume_pos</literal></entry>
<entry>
File offset at which to begin transfer.
Applies to read mode (downloading) only.
</entry>
<entry>0 (Beginning of File)</entry>
</row>
<row>
<entry><literal>proxy</literal> (PHP 5.1.0 or greater)</entry>
<entry>
Proxy FTP request via http proxy server.
Applies to file read operations only.
Ex: <literal>tcp://squid.example.com:8000</literal>
</entry>
<entry/>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<title>Underlying socket stream context options</title>
<simpara>
Additional context options may be supported by the
<link linkend="transports.inet">underlying transport</link>
For <literal>ftp://</literal> streams, refer to context
options for the <literal>tcp://</literal> transport. For
<literal>ftps://</literal> streams, refer to context options
for the <literal>ssl://</literal> transport.
</simpara>
</note>
</section>
<section xml:id="wrappers.php">

46
language/context.xml Normal file
View file

@ -0,0 +1,46 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<reference xml:id="context" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Context options and parameters</title>
<partintro>
<para>
PHP offers various context options and parameters which can be used with all
filesystem and stream wrappers. The context is create created with
<function>stream_context_create</function>. Options are set with
<function>stream_context_set_option</function> and parameters with
<function>stream_context_set_params</function>.
</para>
</partintro>
&language.context.socket;
&language.context.http;
&language.context.ftp;
&language.context.ssl;
&language.context.curl;
&language.context.parameters;
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

215
language/context/curl.xml Normal file
View file

@ -0,0 +1,215 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="context.curl" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>CURL context options</refname>
<refpurpose>CURL context option listing</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<para>
CURL context options are available when the
<link linkend="intro.curl">CURL</link> extension was compiled using the
<option>--with-curlwrappers</option> configure option.
</para>
</refsect1>
<refsect1 role="options"><!-- {{{ -->
&reftitle.options;
<para>
<variablelist>
<varlistentry xml:id="context.curl.method">
<term>
<parameter>method</parameter>
<type>string</type>
</term>
<listitem>
<para>
<constant>GET</constant>, <constant>POST</constant>, or
any other HTTP method supported by the remote server.
</para>
<para>
Defaults to <constant>GET</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.curl.header">
<term>
<parameter>header</parameter>
<type>string</type>
</term>
<listitem>
<para>
Additional headers to be sent during request. Values
in this option will override other values (such as
<literal>User-agent:</literal>, <literal>Host:</literal>,
and <literal>Authentication:</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.curl.user-agent">
<term>
<parameter>user_agent</parameter>
<type>string</type>
</term>
<listitem>
<para>
Value to send with User-Agent: header.
</para>
<para>
By default the
<link linkend="ini.user-agent">user_agent</link>
&php.ini; setting is used.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.curl.content">
<term>
<parameter>content</parameter>
<type>string</type>
</term>
<listitem>
<para>
Additional data to be sent after the headers. This option is not used
for <constant>GET</constant> or <constant>HEAD</constant> requests.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.curl.proxy">
<term>
<parameter>proxy</parameter>
<type>string</type>
</term>
<listitem>
<para>
URI specifying address of proxy server. (e.g.
<literal>tcp://proxy.example.com:5100</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.curl.max-redirects">
<term>
<parameter>max_redirects</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The max number of redirects to follow. Value <literal>1</literal> or
less means that no redirects are followed.
</para>
<para>
Defaults to <literal>20</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.curl.curl-verify-ssl-host">
<term>
<parameter>curl_verify_ssl_host</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Verify the host.
</para>
<para>
Defaults to &false;
</para>
<note>
<para>
This option is available for both the http and ftp protocol wrappers.
</para>
</note>
</listitem>
</varlistentry>
<varlistentry xml:id="context.curl.curl-verify-ssl-peer">
<term>
<parameter>curl_verify_ssl_peer</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Require verification of SSL certificate used.
</para>
<para>
Defaults to &false;
</para>
<note>
<para>
This option is available for both the http and ftp protocol wrappers.
</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1><!-- }}} -->
<refsect1 role="examples"><!-- {{{ -->
&reftitle.examples;
<para>
<example xml:id="context.curl.example-post"><!-- {{{ -->
<title>Fetch a page and send POST data</title>
<programlisting role="php">
<![CDATA[
<?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);
?>
]]>
</programlisting>
</example><!-- }}} -->
</para>
</refsect1><!-- }}} -->
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><xref linkend="context.socket" /></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

144
language/context/ftp.xml Normal file
View file

@ -0,0 +1,144 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="context.ftp" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>FTP context options</refname>
<refpurpose>FTP context option listing</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<para>
Context options for <literal>ftp://</literal> and <literal>ftps://</literal>
transports.
</para>
</refsect1>
<refsect1 role="options"><!-- {{{ -->
&reftitle.options;
<para>
<variablelist>
<varlistentry xml:id="context.ftp.overwrite">
<term>
<parameter>overwrite</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Allow overwriting of already existing files on remote server.
Applies to write mode (uploading) only.
</para>
<para>
Defaults to &false;.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.ftp.resume-pos">
<term>
<parameter>resume_pos</parameter>
<type>integer</type>
</term>
<listitem>
<para>
File offset at which to begin transfer. Applies to read mode (downloading) only.
</para>
<para>
Defaults to <literal>0</literal> (Beginning of File).
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.ftp.proxy">
<term>
<parameter>proxy</parameter>
<type>string</type>
</term>
<listitem>
<para>
Proxy FTP request via http proxy server. Applies to file read
operations only. Ex: <literal>tcp://squid.example.com:8000</literal>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1><!-- }}} -->
<refsect1 role="changelog"><!-- {{{ -->
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>5.1.0</entry>
<entry>
Added <parameter>proxy</parameter>.
</entry>
</row>
<row>
<entry>5.0.0</entry>
<entry>
Added <parameter>overwrite</parameter> and <parameter>resume_pos</parameter>.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1><!-- }}} -->
<refsect1 role="notes">
&reftitle.notes;
<note>
<title>Underlying socket stream context options</title>
<simpara>
Additional context options may be supported by the
<link linkend="transports.inet">underlying transport</link>
For <literal>ftp://</literal> streams, refer to context
options for the <literal>tcp://</literal> transport. For
<literal>ftps://</literal> streams, refer to context options
for the <literal>ssl://</literal> transport.
</simpara>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><xref linkend="context.socket" /></member>
<member><xref linkend="context.ssl" /></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

303
language/context/http.xml Normal file
View file

@ -0,0 +1,303 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="context.http" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>HTTP context options</refname>
<refpurpose>HTTP context option listing</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<para>
Context options for <literal>http://</literal> and <literal>https://</literal>
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>, or
any other HTTP method supported by the remote server.
</para>
<para>
Defaults to <constant>GET</constant>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.http.header">
<term>
<parameter>header</parameter>
<type>string</type>
</term>
<listitem>
<para>
Additional headers to be sent during request. Values
in this option will override other values (such as
<literal>User-agent:</literal>, <literal>Host:</literal>,
and <literal>Authentication:</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.http.user-agent">
<term>
<parameter>user_agent</parameter>
<type>string</type>
</term>
<listitem>
<para>
Value to send with User-Agent: header. This value will
only be used if user-agent is <emphasis>not</emphasis> specified
in the <literal>header</literal> context option above.
</para>
<para>
By default the
<link linkend="ini.user-agent">user_agent</link>
&php.ini; setting is used.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.http.content">
<term>
<parameter>content</parameter>
<type>string</type>
</term>
<listitem>
<para>
Additional data to be sent after the headers. Typically used
with POST or PUT requests.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.http.proxy">
<term>
<parameter>proxy</parameter>
<type>string</type>
</term>
<listitem>
<para>
URI specifying address of proxy server. (e.g.
<literal>tcp://proxy.example.com:5100</literal>).
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.http.request-fulluri">
<term>
<parameter>request_fulluri</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
When set to &true;, the entire URI will be used when
constructing the request. (i.e.
<literal>GET http://www.example.com/path/to/file.html HTTP/1.0</literal>).
While this is a non-standard request format, some
proxy servers require it.
</para>
<para>
Defaults to &false;.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.http.max-redirects">
<term>
<parameter>max_redirects</parameter>
<type>integer</type>
</term>
<listitem>
<para>
The max number of redirects to follow. Value <literal>1</literal> or
less means that no redirects are followed.
</para>
<para>
Defaults to <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 protocol version.
</para>
<para>
Defaults to <literal>1.0</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.http.timeout">
<term>
<parameter>timeout</parameter>
<type>float</type>
</term>
<listitem>
<para>
Read timeout in seconds, specified by a <type>float</type>
(e.g. <literal>10.5</literal>).
</para>
<para>
By default the
<link linkend="ini.default-socket-timeout">default_socket_timeout</link>
&php.ini; setting is used.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.http.ignore-errors">
<term>
<parameter>ignore_errors</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Fetch the content even on failure status codes.
</para>
<para>
Defaults to &false;
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1><!-- }}} -->
<refsect1 role="changelog"><!-- {{{ -->
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>5.3.0</entry>
<entry>
Added <parameter>ignore_errors</parameter>.
</entry>
</row>
<row>
<entry>5.2.1</entry>
<entry>
Added <parameter>timeout</parameter>.
</entry>
</row>
<row>
<entry>5.1.0</entry>
<entry>
Added HTTPS proxying through HTTP proxies.
</entry>
<entry>5.1.0</entry>
<entry>
Added <parameter>max_redirects</parameter>.
</entry>
</row>
<row>
<entry>5.1.0</entry>
<entry>
Added <parameter>protocol_version</parameter>.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1><!-- }}} -->
<refsect1 role="examples"><!-- {{{ -->
&reftitle.examples;
<para>
<example xml:id="context.http.example-post"><!-- {{{ -->
<title>Fetch a page and send POST data</title>
<programlisting role="php">
<![CDATA[
<?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);
?>
]]>
</programlisting>
</example><!-- }}} -->
</para>
</refsect1><!-- }}} -->
<refsect1 role="notes">
&reftitle.notes;
<note>
<title>Underlying socket stream context options</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>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><xref linkend="context.socket" /></member>
<member><xref linkend="context.ssl" /></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

62
language/context/parameters.xml Normal file
View file

@ -0,0 +1,62 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="context.params" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Context parameters</refname>
<refpurpose>Context parameter listing</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<para>
These <literal>parameters</literal> can be set on a <literal>context</literal>
using the <function>stream_context_set_params</function> function.
</para>
</refsect1>
<refsect1 role="options"><!-- {{{ -->
&reftitle.options;
<para>
<variablelist>
<varlistentry xml:id="context.params.notification">
<term>
<parameter>notification</parameter>
<type>callback</type>
</term>
<listitem>
<para>
A <type>callback</type> to be called when an event occurs on a stream.
</para>
<para>
See <function>stream_notification_callback</function> for more details.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1><!-- }}} -->
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

136
language/context/socket.xml Normal file
View file

@ -0,0 +1,136 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="context.socket" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Socket context options</refname>
<refpurpose>Socket context option listing</refpurpose>
</refnamediv>
<refsect1 role="description"><!-- {{{ -->
&reftitle.description;
<para>
Socket context options are available for all wrappers that work over
sockets, like <literal>tcp</literal>, <literal>http</literal> and
<literal>ftp</literal>.
</para>
</refsect1><!-- }}} -->
<refsect1 role="options"><!-- {{{ -->
&reftitle.options;
<para>
<variablelist>
<varlistentry xml:id="context.socket.bindto">
<term><parameter>bindto</parameter></term>
<listitem>
<para>
Used to specify the IP address (either IPv4 or IPv6) and/or the
port number that PHP will use to access the network. The syntax
is <literal>ip:port</literal>.
Setting the IP or the port to <literal>0</literal> will let the system
choose the IP and/or port.
</para>
<note>
<para>
As FTP creates two socket connections during normal operation,
the port number cannot be specified using this option.
</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1><!-- }}} -->
<refsect1 role="changelog"><!-- {{{ -->
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>5.1.0</entry>
<entry>
Added <literal>bindto</literal>.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1><!-- }}} -->
<refsect1 role="examples"><!-- {{{ -->
&reftitle.examples;
<para>
<example xml:id="context.socket.example-bindto"><!-- {{{ -->
<title>Basic <parameter>bindto</parameter> usage example</title>
<programlisting role="php">
<![CDATA[
<?php
// connect to the internet using the '192.168.0.100' IP
$opts = array(
'socket' => array(
'bindto' => '192.168.0.100:0',
),
);
// connect to the internet using the '192.168.0.100' IP and port '7000'
$opts = array(
'socket' => array(
'bindto' => '192.168.0.100:7000',
),
);
// connect to the internet using port '7000'
$opts = array(
'socket' => array(
'bindto' => '0:7000',
),
);
// create the context...
$context = stream_context_create($opts);
// ...and use it to fetch the data
echo file_get_contents('http://www.example.com', false, $context);
?>
]]>
</programlisting>
</example><!-- }}} -->
</para>
</refsect1><!-- }}} -->
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

242
language/context/ssl.xml Normal file
View file

@ -0,0 +1,242 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 1.1 $ -->
<refentry xml:id="context.ssl" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>SSL context options</refname>
<refpurpose>SSL context option listing</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<para>
Context options for <literal>ssl://</literal> and <literal>tls://</literal>
transports.
</para>
</refsect1>
<refsect1 role="options"><!-- {{{ -->
&reftitle.options;
<para>
<variablelist>
<varlistentry xml:id="context.ssl.verify-peer">
<term>
<parameter>verify_peer</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Require verification of SSL certificate used.
</para>
<para>
Defaults to &false;.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.ssl.allow-self-signed">
<term>
<parameter>allow_self_signed</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
Allow self-signed certificates.
</para>
<para>
Defaults to &false;
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.ssl.cafile">
<term>
<parameter>cafile</parameter>
<type>string</type>
</term>
<listitem>
<para>
Location of Certificate Authority file on local filesystem
which should be used with the <literal>verify_peer</literal>
context option to authenticate the identity of the remote peer.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.ssl.capath">
<term>
<parameter>capath</parameter>
<type>string</type>
</term>
<listitem>
<para>
If <literal>cafile</literal> is not specified or if the certificate
is not found there, the directory pointed to by <literal>capath</literal>
is searched for a suitable certificate. <literal>capath</literal>
must be a correctly hashed certificate directory.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.ssl.local-cert">
<term>
<parameter>local_cert</parameter>
<type>string</type>
</term>
<listitem>
<para>
Path to local certificate file on filesystem. It must be a PEM
encoded file which contains your certificate and private key.
It can optionally contain the certificate chain of issuers.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.ssl.passphrase">
<term>
<parameter>passphrase</parameter>
<type>string</type>
</term>
<listitem>
<para>
Passphrase with which your <literal>local_cert</literal> file
was encoded.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.ssl.cn-match">
<term>
<parameter>CN_match</parameter>
<type>string</type>
</term>
<listitem>
<para>
Common Name we are expecting. PHP will perform limited wildcard
matching. If the Common Name does not match this, the connection
attempt will fail.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.ssl.verify-depth">
<term>
<parameter>verify_depth</parameter>
<type>integer</type>
</term>
<listitem>
<para>
Abort if the certificate chain is too deep.
</para>
<para>
Defaults to no verification.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.ssl.ciphers">
<term>
<parameter>ciphers</parameter>
<type>string</type>
</term>
<listitem>
<para>
Sets the list of available ciphers. The format of the string is described
in <link xlink:href="&url.openssl.ciphers;">ciphers(1)</link>.
</para>
<para>
Defaults to <literal>DEFAULT</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.ssl.capture-peer-cert">
<term>
<parameter>capture_peer_cert</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
If set to &true; a <literal>peer_certificate</literal> context option
will be created containing the peer certificate.
</para>
</listitem>
</varlistentry>
<varlistentry xml:id="context.ssl.capture-peer-chain">
<term>
<parameter>capture_peer_chain</parameter>
<type>boolean</type>
</term>
<listitem>
<para>
If set to &true; a <literal>peer_certificate_chain</literal> context
option will be created containing the certificate chain.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1><!-- }}} -->
<refsect1 role="changelog"><!-- {{{ -->
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>5.0.0</entry>
<entry>
Added <parameter>capture_peer_cert</parameter>,
<parameter>capture_peer_chain</parameter> and
<parameter>ciphers</parameter>.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1><!-- }}} -->
<refsect1 role="notes">
&reftitle.notes;
<note>
<simpara>
Because <literal>ssl://</literal> is the underlying transport for the
<link linkend="wrappers.http"><literal>https://</literal></link> and
<link linkend="wrappers.ftp"><literal>ftps://</literal></link> wrappers,
any context options which apply to <literal>ssl://</literal> also apply to
<literal>https://</literal> and <literal>ftps://</literal>.
</simpara>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><xref linkend="context.socket" /></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->