update v1.0.7.9 R.C.

This is a Release Candidate. We are still testing.

vendor/zendframework/zend-http/doc/book/zend.http.client.md

@@ -0,0 +1,230 @@
+# HTTP Client
+
+## Overview
+
+`Zend\Http\Client` provides an easy interface for performing Hyper-Text Transfer Protocol (HTTP)
+requests. `Zend\Http\Client` supports the most simple features expected from an *HTTP* client, as
+well as some more complex features such as *HTTP* authentication and file uploads. Successful
+requests (and most unsuccessful ones too) return a `Zend\Http\Response` object, which provides
+access to the response's headers and body (see this
+section <zend.http.response>).
+
+## Quick Start
+
+The class constructor optionally accepts a URL as its first parameter (can be either a string or a
+`Zend\Uri\Http` object), and an array or `Zend\Config\Config` object containing configuration
+options. The `send()` method is used to submit the request to the remote server, and a
+`Zend\Http\Response` object is returned:
+
+```php
+use Zend\Http\Client;
+
+$client = new Client('http://example.org', array(
+    'maxredirects' => 0,
+    'timeout'      => 30
+));
+$response = $client->send();
+```
+
+Both constructor parameters can be left out, and set later using the setUri() and setConfig()
+methods:
+
+```php
+use Zend\Http\Client;
+
+$client = new Client();
+$client->setUri('http://example.org');
+$client->setOptions(array(
+    'maxredirects' => 0,
+    'timeout'      => 30
+));
+$response = $client->send();
+```
+
+`Zend\Http\Client` can also dispatch requests using a separately configured `request` object (see
+the Zend\\\\Http\\\\Request manual page<zend.http.request> for full details of the methods
+available):
+
+```php
+use Zend\Http\Client;
+use Zend\Http\Request;
+
+$request = new Request();
+$request->setUri('http://example.org');
+
+$client = new Client();
+
+$response = $client->send($request);
+```
+
+> ## Note
+`Zend\Http\Client` uses `Zend\Uri\Http` to validate URLs. See the Zend\\\\Uri manual
+page<zend.uri> for more information on the validation process.
+
+## Configuration
+
+The constructor and setOptions() method accepts an associative array of configuration parameters, or
+a `Zend\Config\Config` object. Setting these parameters is optional, as they all have default
+values.
+
+The options are also passed to the adapter class upon instantiation, so the same array or
+`Zend\Config\Config` object) can be used for adapter configuration. See the Zend Http Client adapter
+section<zend.http.client.adapters> for more information on the adapter-specific options
+available.
+
+## Examples
+
+### Performing a Simple GET Request
+
+Performing simple *HTTP* requests is very easily done:
+
+```php
+use Zend\Http\Client;
+
+$client = new Client('http://example.org');
+$response = $client->send();
+```
+
+### Using Request Methods Other Than GET
+
+The request method can be set using `setMethod()`. If no method is specified, the method set by the
+last `setMethod()` call is used. If `setMethod()` was never called, the default request method is
+`GET`.
+
+```php
+use Zend\Http\Client;
+
+$client = new Client('http://example.org');
+
+// Performing a POST request
+$client->setMethod('POST');
+$response = $client->send();
+```
+
+For convenience, `Zend\Http\Request` defines all the request methods as class constants,
+`Zend\Http\Request::METHOD_GET`, `Zend\Http\Request::METHOD_POST` and so on:
+
+```php
+use Zend\Http\Client;
+use Zend\Http\Request;
+
+$client = new Client('http://example.org');
+
+// Performing a POST request
+$client->setMethod(Request::METHOD_POST);
+$response = $client->send();
+```
+
+### Setting GET parameters
+
+Adding `GET` parameters to an *HTTP* request is quite simple, and can be done either by specifying
+them as part of the URL, or by using the `setParameterGet()` method. This method takes the `GET`
+parameters as an associative array of name => value `GET` variables.
+
+```php
+use Zend\Http\Client;
+$client = new Client();
+
+// This is equivalent to setting a URL in the Client's constructor:
+$client->setUri('http://example.com/index.php?knight=lancelot');
+
+// Adding several parameters with one call
+$client->setParameterGet(array(
+   'first_name'  => 'Bender',
+   'middle_name' => 'Bending',
+   'last_name'   => 'Rodríguez',
+   'made_in'     => 'Mexico',
+));
+```
+
+### Setting POST Parameters
+
+While `GET` parameters can be sent with every request method, `POST` parameters are only sent in the
+body of `POST` requests. Adding `POST` parameters to a request is very similar to adding `GET`
+parameters, and can be done with the `setParameterPost()` method, which is identical to the
+`setParameterGet()` method in structure.
+
+```php
+use Zend\Http\Client;
+
+$client = new Client();
+
+// Setting several POST parameters, one of them with several values
+$client->setParameterPost(array(
+    'language'  => 'es',
+    'country'   => 'ar',
+    'selection' => array(45, 32, 80)
+));
+```
+
+Note that when sending `POST` requests, you can set both `GET` and `POST` parameters. On the other
+hand, setting POST parameters on a non-`POST` request will not trigger an error, rendering it
+useless. Unless the request is a `POST` request, `POST` parameters are simply ignored.
+
+### Connecting to SSL URLs
+
+If you are trying to connect to an SSL (https) URL and are using the default
+(`Zend\Http\Client\Adapter\Socket`) adapter, you may need to set the `sslcapath` configuration
+option in order to allow PHP to validate the SSL certificate:
+
+```php
+use Zend\Http\Client;
+
+$client = new Client('https://example.org', array(
+   'sslcapath' => '/etc/ssl/certs'
+));
+$response = $client->send();
+```
+
+The exact path to use will vary depending on your Operating System. Without this you'll get the
+exception "Unable to enable crypto on TCP connection" when trying to connect.
+
+Alternatively, you could switch to the curl adapter, which negotiates SSL connections more
+transparently:
+
+```php
+use Zend\Http\Client;
+
+$client = new Client('https://example.org', array(
+   'adapter' => 'Zend\Http\Client\Adapter\Curl'
+));
+$response = $client->send();
+```
+
+### A Complete Example
+
+```php
+use Zend\Http\Client;
+
+$client = new Client();
+$client->setUri('http://www.example.com');
+$client->setMethod('POST');
+$client->setParameterPost(array(
+   'foo' => 'bar'
+));
+
+$response = $client->send();
+
+if ($response->isSuccess()) {
+    // the POST was successful
+}
+```
+
+or the same thing, using a request object:
+
+```php
+use Zend\Http\Client;
+use Zend\Http\Request;
+
+$request = new Request();
+$request->setUri('http://www.example.com');
+$request->setMethod('POST');
+$request->getPost()->set('foo', 'bar');
+
+$client = new Client();
+$response = $client->send($request);
+
+if ($response->isSuccess()) {
+    // the POST was successful
+}
+```