Hi all Attached is a patch refactoring context options into its own reference page under the language reference. Pretty much only refactoring and new markup, almost no new content.
-Hannes
Index: manual.xml.in =================================================================== RCS file: /repository/phpdoc/manual.xml.in,v retrieving revision 1.249 diff -u -p -r1.249 manual.xml.in --- manual.xml.in 11 Apr 2008 22:27:43 -0000 1.249 +++ manual.xml.in 13 Apr 2008 22:04:33 -0000 @@ -97,6 +97,7 @@ &language.namespaces; &language.exceptions; &language.references; + &language.context; </book> <book xml:id="security"> Index: en/language-defs.ent =================================================================== RCS file: /repository/phpdoc/en/language-defs.ent,v retrieving revision 1.37 diff -u -p -r1.37 language-defs.ent --- en/language-defs.ent 27 Dec 2007 03:14:48 -0000 1.37 +++ en/language-defs.ent 13 Apr 2008 22:04:33 -0000 @@ -79,6 +79,7 @@ supplemental files to mark section title <!ENTITY reftitle.methods '<title>Methods</title>'> <!ENTITY reftitle.notes '<title>Notes</title>'> <!ENTITY reftitle.parameters '<title>Parameters</title>'> +<!ENTITY reftitle.options '<title>Options</title>'> <!ENTITY reftitle.properties '<title>Properties</title>'> <!ENTITY reftitle.required '<title>Requirements</title>'> <!ENTITY reftitle.resources '<title>Resource Types</title>'> Index: en/language/context.xml =================================================================== RCS file: en/language/context.xml diff -N en/language/context.xml --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ en/language/context.xml 13 Apr 2008 22:04:33 -0000 @@ -0,0 +1,47 @@ +<?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; + --> + +</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 +--> + Index: en/appendices/transports.xml =================================================================== RCS file: /repository/phpdoc/en/appendices/transports.xml,v retrieving revision 1.16 diff -u -p -r1.16 transports.xml --- en/appendices/transports.xml 13 Apr 2008 18:43:39 -0000 1.16 +++ en/appendices/transports.xml 13 Apr 2008 22:04:33 -0000 @@ -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"> Index: en/appendices/wrappers.xml =================================================================== RCS file: /repository/phpdoc/en/appendices/wrappers.xml,v retrieving revision 1.78 diff -u -p -r1.78 wrappers.xml --- en/appendices/wrappers.xml 13 Apr 2008 17:24:45 -0000 1.78 +++ en/appendices/wrappers.xml 13 Apr 2008 22:04:33 -0000 @@ -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 $r ]]> </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://exam </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"> Index: en/language/context/ftp.xml =================================================================== RCS file: en/language/context/ftp.xml diff -N en/language/context/ftp.xml --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ en/language/context/ftp.xml 13 Apr 2008 22:04:33 -0000 @@ -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 +--> + Index: en/language/context/http.xml =================================================================== RCS file: en/language/context/http.xml diff -N en/language/context/http.xml --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ en/language/context/http.xml 13 Apr 2008 22:04:33 -0000 @@ -0,0 +1,301 @@ +<?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 <xref linkend="ini.user-agent" /> + &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 <xref linkend="ini.default-socket-timeout" /> + &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 +--> + Index: en/language/context/socket.xml =================================================================== RCS file: en/language/context/socket.xml diff -N en/language/context/socket.xml --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ en/language/context/socket.xml 13 Apr 2008 22:04:33 -0000 @@ -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 +--> + Index: en/language/context/ssl.xml =================================================================== RCS file: en/language/context/ssl.xml diff -N en/language/context/ssl.xml --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ en/language/context/ssl.xml 13 Apr 2008 22:04:33 -0000 @@ -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 +--> +
