This page has moved.
' + . '' +); + +// Set the next successive response +$adapter->addResponse( + "HTTP/1.1 200 OK\r\n" + . "Content-Type: text/html\r\n" + . "\r\n" + . '' + . '...
' + . '' +); + +// inject the http client object ($client) into your object +// being tested and then test your object's behavior below +``` + +The `setResponse()` method clears any responses in the adapter's buffer and sets +the first response that will be returned. The `addResponse()` method will add +successive responses. + +The responses will be replayed in the order that they were added. If more +requests are made than the number of responses stored, the responses will cycle +again in order. + +In the example above, the adapter is configured to test your object's behavior +when it encounters a 302 redirect. Depending on your application, following a +redirect may or may not be desired behavior. In our example, we expect that the +redirect will be followed and we configure the test adapter to help us test +this. The initial 302 response is set up with the `setResponse()` method and the +200 response to be returned next is added with the `addResponse()` method. After +configuring the test adapter, inject the HTTP client containing the adapter into +your object under test and test its behavior. + +### Forcing the adapter to fail + +If you need the adapter to fail on demand you can use +`setNextRequestWillFail($flag)`. The method will cause the next call to +`connect()` to throw an `Zend\Http\Client\Adapter\Exception\RuntimeException`. +This can be useful when our application caches content from an external site (in +case the site goes down) and you want to test this feature. + +```php +use Zend\Http\Client; + +// Instantiate a new adapter and client +$adapter = new Client\Adapter\Test(); +$client = new Client( + 'http://www.example.com', + ['adapter' => $adapter] +); + +// Force the next request to fail with an exception +$adapter->setNextRequestWillFail(true); + +try { + // This call will result in an exception. + $client->send(); +} catch (Client\Adapter\Exception\RuntimeException $e) { + // ... +} + +// Further requests will work as expected until +// you call setNextRequestWillFail(true) again +``` + +## Creating your own connection adapters + +`Zend\Http\Client` has been designed so that you can create and use your own +connection adapters. You could, for example, create a connection adapter that +uses persistent sockets, or a connection adapter with caching abilities, and use +them as needed in your application. + +In order to do so, you must create your own adapter class that implements +`Zend\Http\Client\Adapter\AdapterInterface`. The following example shows the +skeleton of a user-implemented adapter class. All the public functions defined +in this example must be defined in your adapter as well. + +```php +namespace MyApp\Http\Client\Adapter; + +use Zend\Http\Client\Adapter\AdapterInterface; + +class BananaProtocol implements AdapterInterface +{ + /** + * Set Adapter Options + * + * @param array $config + */ + public function setOptions($config = []) + { + // This rarely changes - you should usually copy the + // implementation in Zend\Http\Client\Adapter\Socket. + } + + /** + * Connect to the remote server + * + * @param string $host + * @param int $port + * @param boolean $secure + */ + public function connect($host, $port = 80, $secure = false) + { + // Set up the connection to the remote server + } + + /** + * Send request to the remote server + * + * @param string $method + * @param Zend\Uri\Http $url + * @param string $http_ver + * @param array $headers + * @param string $body + * @return string Request as text + */ + public function write( + $method, + $url, + $http_ver = '1.1', + $headers = [], + $body = '' + ) { + // Send request to the remote server. + // This function is expected to return the full request + // (headers and body) as a string + } + + /** + * Read response from server + * + * @return string + */ + public function read() + { + // Read response from remote server and return it as a string + } + + /** + * Close the connection to the server + * + */ + public function close() + { + // Close the connection to the remote server - called last. + } +} +``` + +Use the adapter as you would any other: + +```php +use MyApp\Http\Client\Adapter\BananaProtocol; +use Zend\Http\Client; + +$client = new Client([ + 'adapter' => BananaProtocol::class, +]); +``` diff --git a/doc/book/client/advanced.md b/doc/book/client/advanced.md new file mode 100644 index 0000000000..849b1f0925 --- /dev/null +++ b/doc/book/client/advanced.md @@ -0,0 +1,357 @@ +# HTTP Client Advanced Usage + +## HTTP redirections + +`Zend\Http\Client` automatically handles HTTP redirections, and by default +will follow up to 5 redirections. This can be changed by setting the +`maxredirects` configuration parameter. + +According to the HTTP/1.1 RFC, HTTP 301 and 302 responses should be treated by +the client by resending the same request to the specified location, using the +same request method. However, most clients to not implement this and always use +a `GET` request when redirecting. By default, `Zend\Http\Client` does the same; +when redirecting on a 301 or 302 response, all query and body parameters are +reset, and a `GET` request is sent to the new location. This behavior can be +changed by setting the `strictredirects` configuration parameter to boolean +`TRUE`: + +```php +// Strict Redirections +$client->setOptions(['strictredirects' => true]); + +// Non-strict Redirections +$client->setOptions(['strictredirects' => false]); +``` + +You can always get the number of redirections done after sending a request +using the `getRedirectionsCount()` method. + +## Adding cookies and using cookie persistence + +`Zend\Http\Client` provides an interface for adding cookies to your request, so +that no direct header modification is required. Cookies can be added using +either the addCookie() or `setCookies()` method. `addCookie()` can accept +either a name and value, a `SetCookie` header instance, or an array of +`SetCookie` header instances. + +```php +use Zend\Http\Header\SetCookie; + +// Basic usage: provide a cookie name and cookie value: +$client->addCookie('flavor', 'chocolate chips'); + +// Or provide a SetCookie instance: +$cookie = SetCookie::fromString('Set-Cookie: flavor=chocolate%20chips'); +$client->addCookie($cookie); + +// Multiple cookies can be set at once by providing an +// array of SetCookie instances: +$cookies = [ + SetCookie::fromString('Set-Cookie: flavorOne=chocolate%20chips'), + SetCookie::fromString('Set-Cookie: flavorTwo=vanilla'), +]; +$client->addCookie($cookies); +``` + +The `setCookies()` method works in a similar manner, except that it requires an +array of cookie name/value pairs as its only argument, and also clears the +cookie container before adding the new cookies: + +```php +// setCookies accepts an array of cookie values as $name => $value +$client->setCookies([ + 'flavor' => 'chocolate chips', + 'amount' => 10, +]); +``` + +See the [Headers documentation](../headers.md#setcookie) for more detail on the +`SetCookie` class. + +### Enabling Cookie Stickiness + +`Zend\Http\Client` also provides a means for simplifying cookie "stickiness" +— i.e., having the client internally store all sent and received cookies, +and resending them on subsequent requests. — via the `Zend\Http\Cookies` +class. This is useful when you need to log in to a remote site first and +receive an authentication or session ID cookie before sending further requests. + +```php +$headers = $client->getRequest()->getHeaders(); +$cookies = new Zend\Http\Cookies($headers); + +// First request: log in and start a session +$client->setUri('http://example.com/login.php'); +$client->setParameterPost(['user' => 'h4x0r', 'password' => 'l33t']); +$client->setMethod('POST'); + +$response = $client->getResponse(); +$cookies->addCookiesFromResponse($response, $client->getUri()); + +// Now we can send our next request +$client->setUri('http://example.com/read_member_news.php'); +$client->setCookies($cookies->getMatchingCookies($client->getUri())); +$client->setMethod('GET'); +``` + +See the chapter on [cookies](cookies.md) for more detail. + +## Setting custom request headers + +Setting custom headers is performed by first fetching the header container from +the client's `Zend\Http\Request` instance. This `Headers` container offers a +number of methods for setting headers: + +```php +use Zend\Http\Header; + +// Fetch the container +$headers = $client->getRequest()->getHeaders(); + +// Setting a single header using a name and value. Will not overwrite any // +previously-added headers of the same name. +$headers->addHeaderLine('Host', 'www.example.com'); + +// You can also use a full header line: +$headers->addHeaderLine('Host: www.example.com'); + +// Sometimes you may want to use a HeaderInterface instance: +$headers->addHeader(Header\Host::fromString('Host: www.example.com')); + +// You can also add multiple headers at once by passing an +// array to addHeaders() using any of the formats below: +$headers->addHeaders([ + // Zend\Http\Header\* instance: + Header\Host::fromString('Host: www.example.com'), + + // Header name/value pair: + 'Cookie' => 'PHPSESSID=1234567890abcdef1234567890abcdef', + + // Raw header string: + 'Cookie: language=he', +]); +``` + +`Zend\Http\Client` also provides a convenience method for setting request +headers, `setHeaders()`. This method will create a new header container, add +the specified headers, and then store the new header container in its +`Zend\Http\Request` instance. As a consequence, any pre-existing headers will +be erased: + +```php +use Zend\Http\Header; + +// Setting multiple headers via the client; removes all existing headers, +// replacing the request header container with the following: +$client->setHeaders([ + Zend\Http\Header\Host::fromString('Host: www.example.com'), + ['Accept-Encoding' => 'gzip,deflate'], + 'X-Powered-By: Zend Framework', +]); +``` + +## File uploads + +You can upload files through HTTP using the `setFileUpload()` method. This +method takes a file name as the first parameter, a form name as the second +parameter, and data as a third optional parameter. If the third data parameter +is `NULL`, the first file name parameter is considered to be a real file on +disk, and `Zend\Http\Client` will try to read this file and upload it. If the +data parameter is not `NULL`, the first file name parameter will be sent as the +file name, but no actual file needs to exist on the disk. The second form name +parameter is always required, and is equivalent to the "name" attribute of an +`` tag, if the file was to be uploaded through an HTML form. A fourth +optional parameter provides the file's `Content-Type`. If not specified, and +`Zend\Http\Client` reads the file from the disk, the `mime_content_type()` +function will be used to guess the file's content type, if it is available. In +any case, the default MIME type will be `application/octet-stream`. + +```php +// Uploading arbitrary data as a file: +$text = 'this is some plain text'; +$client->setFileUpload('some_text.txt', 'upload', $text, 'text/plain'); + +// Uploading an existing file: +$client->setFileUpload('/tmp/Backup.tar.gz', 'bufile'); + +// Send the files: +$client->setMethod('POST'); +$client->send(); +``` + +In the first example, the `$text` variable is uploaded and will be available as +`$_FILES['upload']` on the server side. In the second example, the existing +file `/tmp/Backup.tar.gz` is uploaded to the server and will be available as +`$_FILES['bufile']`. The content type will be guessed automatically if +possible, defaulting to `application/octet-stream`. + +> ### Uploading files +> +> When uploading files, the HTTP request `Content-Type` is automatically set to +> `multipart/form-data`. Keep in mind that you must send a POST or PUT request +> in order to upload files; most servers will ignore the request body on other +> request methods. + +## Sending raw POST data + +You can send raw POST data via `Zend\Http\Client` using the `setRawBody()` +method. This method takes one parameter: the data to send in the request body. +When sending raw POST data, it is advisable to also set the encoding type using +`setEncType()`. + +```php +$xml = 'HTTP message and header abstractions, and HTTP client implementation. (Not a PSR-7 implementation; see Diactoros for PSR-7 support.
+ +$ composer require zendframework/zend-http