From 71a0e2144a1e5a49c896e3e0776d92c768118488 Mon Sep 17 00:00:00 2001 From: Hannes Magnusson Date: Mon, 14 Apr 2008 17:24:12 +0000 Subject: [PATCH] - Refactor stream context options and stream context parameters - Document the curl context options git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@257496 c90b9560-bf6c-de11-be94-00142212c4b1 --- appendices/transports.xml | 126 +------------ appendices/wrappers.xml | 250 +------------------------- language/context.xml | 46 +++++ language/context/curl.xml | 215 ++++++++++++++++++++++ language/context/ftp.xml | 144 +++++++++++++++ language/context/http.xml | 303 ++++++++++++++++++++++++++++++++ language/context/parameters.xml | 62 +++++++ language/context/socket.xml | 136 ++++++++++++++ language/context/ssl.xml | 242 +++++++++++++++++++++++++ 9 files changed, 1150 insertions(+), 374 deletions(-) create mode 100644 language/context.xml create mode 100644 language/context/curl.xml create mode 100644 language/context/ftp.xml create mode 100644 language/context/http.xml create mode 100644 language/context/parameters.xml create mode 100644 language/context/socket.xml create mode 100644 language/context/ssl.xml diff --git a/appendices/transports.xml b/appendices/transports.xml index 89abadb635..3d3046f7c6 100644 --- a/appendices/transports.xml +++ b/appendices/transports.xml @@ -1,5 +1,5 @@ - + List of Supported Socket Transports @@ -88,130 +88,6 @@ sslv3:// will select the SSL V2 or SSL V3 protocol explicitly. - - - - - Context options for <literal>ssl://</literal> and <literal>tls://</literal> - transports (since PHP 4.3.2) - - - - - Name - Usage - Default - - - - - verify_peer - - &true; or &false;. - Require verification of SSL certificate used. - - &false; - - - allow_self_signed - - &true; or &false;. - Allow self-signed certificates. - - &false; - - - cafile - - Location of Certificate Authority file on local filesystem - which should be used with the verify_peer - context option to authenticate the identity of the remote peer. - - - - - capath - - If cafile is not specified or if the certificate - is not found there, the directory pointed to by capath - is searched for a suitable certificate. capath - must be a correctly hashed certificate directory. - - - - - local_cert - - 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. - - - - - passphrase - - Passphrase with which your local_cert file - was encoded. - - - - - CN_match - - Common Name we are expecting. PHP will perform limited wildcard - matching. If the Common Name does not match this, the connection - attempt will fail. - - - - - verify_depth - - Abort if the certificate chain is too deep. - - - - - ciphers - - Sets the list of available ciphers. The format of the string is described - in ciphers(1). Added - in PHP 5.0.0. - - DEFAULT - - - capture_peer_cert - - If set to &true; a peer_certificate context option - will be created containing the peer certificate. Added in PHP 5.0.0. - - &false; - - - capture_peer_cert_chain - - If set to &true; a peer_certificate_chain context - option will be created containing the certificate chain. Added in PHP - 5.0.0. - - &false; - - - -
- - - - - Because ssl:// is the underlying transport for the - https:// and - ftps:// wrappers, - any context options which apply to ssl:// also apply to - https:// and ftps://. - -
diff --git a/appendices/wrappers.xml b/appendices/wrappers.xml index 939a127962..e893b6fac8 100644 --- a/appendices/wrappers.xml +++ b/appendices/wrappers.xml @@ -1,5 +1,5 @@ - + List of Supported Protocols/Wrappers @@ -95,59 +95,6 @@
-
- Socket - - This section contains the context options supported by the wrappers that - work over sockets, like tcp, http or - ftp. - - - As of PHP 5.1.0 only one option is supported, bindto, - 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 - ip:port (you can set the IP or the port number to - 0 if you want to let the system choose them for you). - - - - As FTP creates two socket connections during normal operation, you cannot - specify the port number in the bindto option. So, the - only supported syntax is ip:0 for the FTP wrapper. - - - - Some examples of how to use the bindto option - - - 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); - -?> -]]> - - -
-
HTTP and HTTPS PHP 4, PHP 5, PHP 6. https:// since PHP 4.3.0 @@ -202,35 +149,6 @@ foreach($meta_data['wrapper_data'] as $response) { ]]> - - Fetch a page and send POST data - - '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); - -?> -]]> - - The stream allows access to the body of the resource; the headers are stored in the @@ -302,120 +220,6 @@ $result = file_get_contents('http://example.com/submit.php', false, $context); - - - Context options - - - - Name - Usage - Default - - - - - method - - GET, POST, or - any other HTTP method supported by the remote server. - - GET - - - header - Additional headers to be sent during request. Values - in this option will override other values (such as - User-agent:, Host:, - and Authentication:). - - - - - user_agent - Value to send with User-Agent: header. This value will - only be used if user-agent is not specified - in the header context option above. - - - &php.ini; setting: user_agent - - - - content - - Additional data to be sent after the headers. Typically used - with POST or PUT requests. - - - - - proxy - - URI specifying address of proxy server. (e.g. - tcp://proxy.example.com:5100). HTTPS proxying - (through HTTP proxies) only works in PHP 5.1.0 or greater. - - - - - request_fulluri - - When set to &true;, the entire URI will be used when - constructing the request. (i.e. - GET http://www.example.com/path/to/file.html HTTP/1.0). - While this is a non-standard request format, some - proxy servers require it. - - &false; - - - max_redirects - - The max number of redirects to follow. Value 1 or - less means that no redirects are followed. - Added in PHP 5.1.0. - - 20 - - - protocol_version - - HTTP protocol version. Added in PHP 5.1.0. - - 1.0 - - - timeout - - Read timeout in seconds, specified by a float (e.g. - 10.5). Added in PHP 5.2.1. - - default_socket_timeout - - - ignore_errors - - Fetch the content even on failure status codes. Added in PHP 5.3.0. - - &false; - - - -
- - - - Underlying socket stream context options - - Additional context options may be supported by the - underlying transport - For http:// streams, refer to context - options for the tcp:// transport. For - https:// streams, refer to context options - for the ssl:// transport. - - Custom headers may be sent with an HTTP request prior to @@ -569,58 +373,6 @@ X-MyCustomHeader: Foo - - - Context options (as of PHP 5.0.0) - - - - Name - Usage - Default - - - - - overwrite - - Allow overwriting of already existing files on remote server. - Applies to write mode (uploading) only. - - &false; (Disabled) - - - resume_pos - - File offset at which to begin transfer. - Applies to read mode (downloading) only. - - 0 (Beginning of File) - - - proxy (PHP 5.1.0 or greater) - - Proxy FTP request via http proxy server. - Applies to file read operations only. - Ex: tcp://squid.example.com:8000 - - - - - -
- - - Underlying socket stream context options - - Additional context options may be supported by the - underlying transport - For ftp:// streams, refer to context - options for the tcp:// transport. For - ftps:// streams, refer to context options - for the ssl:// transport. - -
diff --git a/language/context.xml b/language/context.xml new file mode 100644 index 0000000000..d10c6139bf --- /dev/null +++ b/language/context.xml @@ -0,0 +1,46 @@ + + + + + Context options and parameters + + + + PHP offers various context options and parameters which can be used with all + filesystem and stream wrappers. The context is create created with + stream_context_create. Options are set with + stream_context_set_option and parameters with + stream_context_set_params. + + + + &language.context.socket; + &language.context.http; + &language.context.ftp; + &language.context.ssl; + &language.context.curl; + &language.context.parameters; + + + + + diff --git a/language/context/curl.xml b/language/context/curl.xml new file mode 100644 index 0000000000..b12b2009c5 --- /dev/null +++ b/language/context/curl.xml @@ -0,0 +1,215 @@ + + + + + + CURL context options + CURL context option listing + + + + &reftitle.description; + + CURL context options are available when the + CURL extension was compiled using the + configure option. + + + + + &reftitle.options; + + + + + method + string + + + + GET, POST, or + any other HTTP method supported by the remote server. + + + Defaults to GET. + + + + + + header + string + + + + Additional headers to be sent during request. Values + in this option will override other values (such as + User-agent:, Host:, + and Authentication:). + + + + + + user_agent + string + + + + Value to send with User-Agent: header. + + + By default the + user_agent + &php.ini; setting is used. + + + + + + content + string + + + + Additional data to be sent after the headers. This option is not used + for GET or HEAD requests. + + + + + + proxy + string + + + + URI specifying address of proxy server. (e.g. + tcp://proxy.example.com:5100). + + + + + + max_redirects + integer + + + + The max number of redirects to follow. Value 1 or + less means that no redirects are followed. + + + Defaults to 20. + + + + + + curl_verify_ssl_host + boolean + + + + Verify the host. + + + Defaults to &false; + + + + This option is available for both the http and ftp protocol wrappers. + + + + + + + curl_verify_ssl_peer + boolean + + + + Require verification of SSL certificate used. + + + Defaults to &false; + + + + This option is available for both the http and ftp protocol wrappers. + + + + + + + + + + &reftitle.examples; + + + Fetch a page and send POST data + + '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); + +?> +]]> + + + + + + + &reftitle.seealso; + + + + + + + + + + + diff --git a/language/context/ftp.xml b/language/context/ftp.xml new file mode 100644 index 0000000000..d288d2e841 --- /dev/null +++ b/language/context/ftp.xml @@ -0,0 +1,144 @@ + + + + + + FTP context options + FTP context option listing + + + + &reftitle.description; + + Context options for ftp:// and ftps:// + transports. + + + + + &reftitle.options; + + + + + overwrite + boolean + + + + Allow overwriting of already existing files on remote server. + Applies to write mode (uploading) only. + + + Defaults to &false;. + + + + + + resume_pos + integer + + + + File offset at which to begin transfer. Applies to read mode (downloading) only. + + + Defaults to 0 (Beginning of File). + + + + + + proxy + string + + + + Proxy FTP request via http proxy server. Applies to file read + operations only. Ex: tcp://squid.example.com:8000. + + + + + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 5.1.0 + + Added proxy. + + + + 5.0.0 + + Added overwrite and resume_pos. + + + + + + + + + + &reftitle.notes; + + Underlying socket stream context options + + Additional context options may be supported by the + underlying transport + For ftp:// streams, refer to context + options for the tcp:// transport. For + ftps:// streams, refer to context options + for the ssl:// transport. + + + + + + &reftitle.seealso; + + + + + + + + + + + + diff --git a/language/context/http.xml b/language/context/http.xml new file mode 100644 index 0000000000..e68802d77c --- /dev/null +++ b/language/context/http.xml @@ -0,0 +1,303 @@ + + + + + + HTTP context options + HTTP context option listing + + + + &reftitle.description; + + Context options for http:// and https:// + transports. + + + + + &reftitle.options; + + + + + method + string + + + + GET, POST, or + any other HTTP method supported by the remote server. + + + Defaults to GET. + + + + + + header + string + + + + Additional headers to be sent during request. Values + in this option will override other values (such as + User-agent:, Host:, + and Authentication:). + + + + + + user_agent + string + + + + Value to send with User-Agent: header. This value will + only be used if user-agent is not specified + in the header context option above. + + + By default the + user_agent + &php.ini; setting is used. + + + + + + content + string + + + + Additional data to be sent after the headers. Typically used + with POST or PUT requests. + + + + + + proxy + string + + + + URI specifying address of proxy server. (e.g. + tcp://proxy.example.com:5100). + + + + + + request_fulluri + boolean + + + + When set to &true;, the entire URI will be used when + constructing the request. (i.e. + GET http://www.example.com/path/to/file.html HTTP/1.0). + While this is a non-standard request format, some + proxy servers require it. + + + Defaults to &false;. + + + + + + max_redirects + integer + + + + The max number of redirects to follow. Value 1 or + less means that no redirects are followed. + + + Defaults to 20. + + + + + + protocol_version + float + + + + HTTP protocol version. + + + Defaults to 1.0. + + + + + + timeout + float + + + + Read timeout in seconds, specified by a float + (e.g. 10.5). + + + By default the + default_socket_timeout + &php.ini; setting is used. + + + + + + ignore_errors + boolean + + + + Fetch the content even on failure status codes. + + + Defaults to &false; + + + + + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 5.3.0 + + Added ignore_errors. + + + + 5.2.1 + + Added timeout. + + + + 5.1.0 + + Added HTTPS proxying through HTTP proxies. + + 5.1.0 + + Added max_redirects. + + + + 5.1.0 + + Added protocol_version. + + + + + + + + + + &reftitle.examples; + + + Fetch a page and send POST data + + '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); + +?> +]]> + + + + + + + &reftitle.notes; + + Underlying socket stream context options + + Additional context options may be supported by the + underlying transport + For http:// streams, refer to context + options for the tcp:// transport. For + https:// streams, refer to context options + for the ssl:// transport. + + + + + + &reftitle.seealso; + + + + + + + + + + + + diff --git a/language/context/parameters.xml b/language/context/parameters.xml new file mode 100644 index 0000000000..dd7c828134 --- /dev/null +++ b/language/context/parameters.xml @@ -0,0 +1,62 @@ + + + + + + Context parameters + Context parameter listing + + + + &reftitle.description; + + These parameters can be set on a context + using the stream_context_set_params function. + + + + + &reftitle.options; + + + + + notification + callback + + + + A callback to be called when an event occurs on a stream. + + + See stream_notification_callback for more details. + + + + + + + + + + + diff --git a/language/context/socket.xml b/language/context/socket.xml new file mode 100644 index 0000000000..3eefe6b93b --- /dev/null +++ b/language/context/socket.xml @@ -0,0 +1,136 @@ + + + + + + Socket context options + Socket context option listing + + + + &reftitle.description; + + Socket context options are available for all wrappers that work over + sockets, like tcp, http and + ftp. + + + + + &reftitle.options; + + + + bindto + + + 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 ip:port. + Setting the IP or the port to 0 will let the system + choose the IP and/or port. + + + + As FTP creates two socket connections during normal operation, + the port number cannot be specified using this option. + + + + + + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 5.1.0 + + Added bindto. + + + + + + + + + + &reftitle.examples; + + + Basic <parameter>bindto</parameter> usage example + + 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); + +?> +]]> + + + + + + + + + diff --git a/language/context/ssl.xml b/language/context/ssl.xml new file mode 100644 index 0000000000..63091b66f8 --- /dev/null +++ b/language/context/ssl.xml @@ -0,0 +1,242 @@ + + + + + + SSL context options + SSL context option listing + + + + &reftitle.description; + + Context options for ssl:// and tls:// + transports. + + + + + &reftitle.options; + + + + + verify_peer + boolean + + + + Require verification of SSL certificate used. + + + Defaults to &false;. + + + + + + allow_self_signed + boolean + + + + Allow self-signed certificates. + + + Defaults to &false; + + + + + + cafile + string + + + + Location of Certificate Authority file on local filesystem + which should be used with the verify_peer + context option to authenticate the identity of the remote peer. + + + + + + capath + string + + + + If cafile is not specified or if the certificate + is not found there, the directory pointed to by capath + is searched for a suitable certificate. capath + must be a correctly hashed certificate directory. + + + + + + local_cert + string + + + + 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. + + + + + + passphrase + string + + + + Passphrase with which your local_cert file + was encoded. + + + + + + CN_match + string + + + + Common Name we are expecting. PHP will perform limited wildcard + matching. If the Common Name does not match this, the connection + attempt will fail. + + + + + + verify_depth + integer + + + + Abort if the certificate chain is too deep. + + + Defaults to no verification. + + + + + + ciphers + string + + + + Sets the list of available ciphers. The format of the string is described + in ciphers(1). + + + Defaults to DEFAULT. + + + + + + capture_peer_cert + boolean + + + + If set to &true; a peer_certificate context option + will be created containing the peer certificate. + + + + + + capture_peer_chain + boolean + + + + If set to &true; a peer_certificate_chain context + option will be created containing the certificate chain. + + + + + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 5.0.0 + + Added capture_peer_cert, + capture_peer_chain and + ciphers. + + + + + + + + + + &reftitle.notes; + + + Because ssl:// is the underlying transport for the + https:// and + ftps:// wrappers, + any context options which apply to ssl:// also apply to + https:// and ftps://. + + + + + + &reftitle.seealso; + + + + + + + + + + +