<commit_before>===============
Request Options
===============

You can customize requests created and transferred by a client using
**request options**. Request options control various aspects of a request
including, headers, query string parameters, timeout settings, the body of a
request, and much more.

All of the following examples use the following client:

.. code-block:: php

    $client = new GuzzleHttp\Client(['base_uri' => 'http://httpbin.org']);


.. _allow_redirects-option:

allow_redirects
---------------

:Summary: Describes the redirect behavior of a request
:Types:
        - bool
        - array
:Default:

    ::

        [
            'max'             => 5,
            'strict'          => false,
            'referer'         => false,
            'protocols'       => ['http', 'https'],
            'track_redirects' => false
        ]

:Constant: ``GuzzleHttp\RequestOptions::ALLOW_REDIRECTS``

Set to ``false`` to disable redirects.

.. code-block:: php

    $res = $client->request('GET', '/redirect/3', ['allow_redirects' => false]);
    echo $res->getStatusCode();
    // 302

Set to ``true`` (the default setting) to enable normal redirects with a maximum
number of 5 redirects.

.. code-block:: php

    $res = $client->request('GET', '/redirect/3');
    echo $res->getStatusCode();
    // 200

You can also pass an associative array containing the following key value
pairs:

- max: (int, default=5) maximum number of allowed redirects.
- strict: (bool, default=false) Set to true to use strict redirects.
  Strict RFC compliant redirects mean that POST redirect requests are sent as
  POST requests vs. doing what most browsers do which is redirect POST requests
  with GET requests.
- referer: (bool, default=false) Set to true to enable adding the Referer
  header when redirecting.
- protocols: (array, default=['http', 'https']) Specified which protocols are
  allowed for redirect requests.
- on_redirect: (callable) PHP callable that is invoked when a redirect
  is encountered. The callable is invoked with the original request and the
  redirect response that was received. Any return value from the on_redirect
  function is ignored.
- track_redirects: (bool) When set to ``true``, each redirected URI encountered
  will be tracked in the ``X-Guzzle-Redirect-History`` header in the order in
  which the redirects were encountered.

.. code-block:: php

    use Psr\Http\Message\RequestInterface;
    use Psr\Http\Message\ResponseInterface;
    use Psr\Http\Message\UriInterface;

    $onRedirect = function(
        RequestInterface $request,
        ResponseInterface $response,
        UriInterface $uri
    ) {
        echo 'Redirecting! ' . $request->getUri() . ' to ' . $uri . "\n";
    };

    $res = $client->request('GET', '/redirect/3', [
        'allow_redirects' => [
            'max'             => 10,        // allow at most 10 redirects.
            'strict'          => true,      // use "strict" RFC compliant redirects.
            'referer'         => true,      // add a Referer header
            'protocols'       => ['https'], // only allow https URLs
            'on_redirect'     => $onRedirect,
            'track_redirects' => true
        ]
    ]);

    echo $res->getStatusCode();
    // 200

    echo $res->getHeaderLine('X-Guzzle-Redirect-History');
    // http://first-redirect, http://second-redirect, etc...

.. warning::

    This option only has an effect if your handler has the
    ``GuzzleHttp\Middleware::redirect`` middleware. This middleware is added
    by default when a client is created with no handler, and is added by
    default when creating a handler with ``GuzzleHttp\default_handler``.


auth
----

:Summary: Pass an array of HTTP authentication parameters to use with the
        request. The array must contain the username in index [0], the password in
        index [1], and you can optionally provide a built-in authentication type in
        index [2]. Pass ``null`` to disable authentication for a request.
:Types:
        - array
        - string
        - null
:Default: None
:Constant: ``GuzzleHttp\RequestOptions::AUTH``

The built-in authentication types are as follows:

basic
    Use `basic HTTP authentication <http://www.ietf.org/rfc/rfc2069.txt>`_
    in the ``Authorization`` header (the default setting used if none is
    specified).

.. code-block:: php

    $client->request('GET', '/get', ['auth' => ['username', 'password']]);

digest
    Use `digest authentication <http://www.ietf.org/rfc/rfc2069.txt>`_
    (must be supported by the HTTP handler).

.. code-block:: php

    $client->request('GET', '/get', [
        'auth' => ['username', 'password', 'digest']
    ]);

.. note::

    This is currently only supported when using the cURL handler, but
    creating a replacement that can be used with any HTTP handler is
    planned.


body
----

:Summary: The ``body`` option is used to control the body of an entity
    enclosing request (e.g., PUT, POST, PATCH).
:Types:
    - string
    - ``fopen()`` resource
    - ``Psr\Http\Message\StreamInterface``
:Default: None
:Constant: ``GuzzleHttp\RequestOptions::BODY``

This setting can be set to any of the following types:

- string

  .. code-block:: php

      // You can send requests that use a string as the message body.
      $client->request('PUT', '/put', ['body' => 'foo']);

- resource returned from ``fopen()``

  .. code-block:: php

      // You can send requests that use a stream resource as the body.
      $resource = fopen('http://httpbin.org', 'r');
      $client->request('PUT', '/put', ['body' => $resource]);

- ``Psr\Http\Message\StreamInterface``

  .. code-block:: php

      // You can send requests that use a Guzzle stream object as the body
      $stream = GuzzleHttp\Psr7\stream_for('contents...');
      $client->request('POST', '/post', ['body' => $stream]);

.. note::

    This option cannot be used with ``form_params``, ``multipart``, or ``json``


.. _cert-option:

cert
----

:Summary: Set to a string to specify the path to a file containing a PEM
        formatted client side certificate. If a password is required, then set to
        an array containing the path to the PEM file in the first array element
        followed by the password required for the certificate in the second array
        element.
:Types:
        - string
        - array
:Default: None
:Constant: ``GuzzleHttp\RequestOptions::CERT``

.. code-block:: php

    $client->request('GET', '/', ['cert' => ['/path/server.pem', 'password']]);


.. _cookies-option:

cookies
-------

:Summary: Specifies whether or not cookies are used in a request or what cookie
        jar to use or what cookies to send.
:Types: ``GuzzleHttp\Cookie\CookieJarInterface``
:Default: None
:Constant: ``GuzzleHttp\RequestOptions::COOKIES``

You must specify the cookies option as a
``GuzzleHttp\Cookie\CookieJarInterface`` or ``false``.

.. code-block:: php

    $jar = new \GuzzleHttp\Cookie\CookieJar();
    $client->request('GET', '/get', ['cookies' => $jar]);

.. warning::

    This option only has an effect if your handler has the
    ``GuzzleHttp\Middleware::cookies`` middleware. This middleware is added
    by default when a client is created with no handler, and is added by
    default when creating a handler with ``GuzzleHttp\default_handler``.

.. tip::

    When creating a client, you can set the default cookie option to ``true``
    to use a shared cookie session associated with the client.


.. _connect_timeout-option:

connect_timeout
---------------

:Summary: Float describing the number of seconds to wait while trying to connect
        to a server. Use ``0`` to wait indefinitely (the default behavior).
:Types: float
:Default: ``0``
:Constant: ``GuzzleHttp\RequestOptions::CONNECT_TIMEOUT``

.. code-block:: php

    // Timeout if the client fails to connect to the server in 3.14 seconds.
    $client->request('GET', '/delay/5', ['connect_timeout' => 3.14]);

.. note::

    This setting must be supported by the HTTP handler used to send a request.
    ``connect_timeout`` is currently only supported by the built-in cURL
    handler.


.. _debug-option:

debug
-----

:Summary: Set to ``true`` or set to a PHP stream returned by ``fopen()`` to
    enable debug output with the handler used to send a request. For example,
    when using cURL to transfer requests, cURL's verbose of ``CURLOPT_VERBOSE``
    will be emitted. When using the PHP stream wrapper, stream wrapper
    notifications will be emitted. If set to true, the output is written to
    PHP's STDOUT. If a PHP stream is provided, output is written to the stream.
:Types:
        - bool
        - ``fopen()`` resource
:Default: None
:Constant: ``GuzzleHttp\RequestOptions::DEBUG``

.. code-block:: php

    $client->request('GET', '/get', ['debug' => true]);

Running the above example would output something like the following:

::

    * About to connect() to httpbin.org port 80 (#0)
    *   Trying 172.16.17.32... * Connected to httpbin.org (172.16.17.32) port 80 (#0)
    > GET /get HTTP/1.1
    Host: httpbin.org
    User-Agent: Guzzle/4.0 curl/7.21.4 PHP/5.5.7

    < HTTP/1.1 200 OK
    < Access-Control-Allow-Origin: *
    < Content-Type: application/json
    < Date: Sun, 16 Feb 2014 06:50:09 GMT
    < Server: gunicorn/0.17.4
    < Content-Length: 335
    < Connection: keep-alive
    <
    * Connection #0 to host httpbin.org left intact


.. _decode_content-option:

decode_content
--------------

:Summary: Specify whether or not ``Content-Encoding`` responses (gzip,
    deflate, etc.) are automatically decoded.
:Types:
        - string
        - bool
:Default: ``true``
:Constant: ``GuzzleHttp\RequestOptions::DECODE_CONTENT``

This option can be used to control how content-encoded response bodies are
handled. By default, ``decode_content`` is set to true, meaning any gzipped
or deflated response will be decoded by Guzzle.

When set to ``false``, the body of a response is never decoded, meaning the
bytes pass through the handler unchanged.

.. code-block:: php

    // Request gzipped data, but do not decode it while downloading
    $client->request('GET', '/foo.js', [
        'headers'        => ['Accept-Encoding' => 'gzip'],
        'decode_content' => false
    ]);

When set to a string, the bytes of a response are decoded and the string value
provided to the ``decode_content`` option is passed as the ``Accept-Encoding``
header of the request.

.. code-block:: php

    // Pass "gzip" as the Accept-Encoding header.
    $client->request('GET', '/foo.js', ['decode_content' => 'gzip']);


.. _delay-option:

delay
-----

:Summary: The number of milliseconds to delay before sending the request.
:Types:
    - integer
    - float
:Default: null
:Constant: ``GuzzleHttp\RequestOptions::DELAY``


.. _expect-option:

expect
------

:Summary: Controls the behavior of the "Expect: 100-Continue" header.
:Types:
    - bool
    - integer
:Default: ``1048576``
:Constant: ``GuzzleHttp\RequestOptions::EXPECT``

Set to ``true`` to enable the "Expect: 100-Continue" header for all requests
that sends a body. Set to ``false`` to disable the "Expect: 100-Continue"
header for all requests. Set to a number so that the size of the payload must
be greater than the number in order to send the Expect header. Setting to a
number will send the Expect header for all requests in which the size of the
payload cannot be determined or where the body is not rewindable.

By default, Guzzle will add the "Expect: 100-Continue" header when the size of
the body of a request is greater than 1 MB and a request is using HTTP/1.1.

.. note::

    This option only takes effect when using HTTP/1.1. The HTTP/1.0 and
    HTTP/2.0 protocols do not support the "Expect: 100-Continue" header.
    Support for handling the "Expect: 100-Continue" workflow must be
    implemented by Guzzle HTTP handlers used by a client.


force_ip_resolve
----------------

:Summary: Set to "v4" if you want the HTTP handlers to use only ipv4 protocol or "v6" for ipv6 protocol.
:Types: string
:Default: null
:Constant: ``GuzzleHttp\RequestOptions::FORCE_IP_RESOLVE``

.. code-block:: php

    // Force ipv4 protocol
    $client->request('GET', '/foo', ['force_ip_resolve' => 'v4']);

    // Force ipv6 protocol
    $client->request('GET', '/foo', ['force_ip_resolve' => 'v6']);

.. note::

    This setting must be supported by the HTTP handler used to send a request.
    ``force_ip_resolve`` is currently only supported by the built-in cURL
    handler.


form_params
-----------

:Summary: Used to send an `application/x-www-form-urlencoded` POST request.
:Types: array
:Constant: ``GuzzleHttp\RequestOptions::FORM_PARAMS``

Associative array of form field names to values where each value is a string or
array of strings. Sets the Content-Type header to
application/x-www-form-urlencoded when no Content-Type header is already
present.

.. code-block:: php

    $client->request('POST', '/post', [
        'form_params' => [
            'foo' => 'bar',
            'baz' => ['hi', 'there!']
        ]
    ]);

.. note::

    ``form_params`` cannot be used with the ``multipart`` option. You will need to use
    one or the other. Use ``form_params`` for ``application/x-www-form-urlencoded``
    requests, and ``multipart`` for ``multipart/form-data`` requests.

    This option cannot be used with ``body``, ``multipart``, or ``json``


headers
-------

:Summary: Associative array of headers to add to the request. Each key is the
    name of a header, and each value is a string or array of strings
    representing the header field values.
:Types: array
:Defaults: None
:Constant: ``GuzzleHttp\RequestOptions::HEADERS``

.. code-block:: php

    // Set various headers on a request
    $client->request('GET', '/get', [
        'headers' => [
            'User-Agent' => 'testing/1.0',
            'Accept'     => 'application/json',
            'X-Foo'      => ['Bar', 'Baz']
        ]
    ]);

Headers may be added as default options when creating a client. When headers
are used as default options, they are only applied if the request being created
does not already contain the specific header. This include both requests passed
to the client in the ``send()`` and ``sendAsync()`` methods and requests
created by the client (e.g., ``request()`` and ``requestAsync()``).

.. code-block:: php

    $client = new GuzzleHttp\Client(['headers' => ['X-Foo' => 'Bar']]);

    // Will send a request with the X-Foo header.
    $client->request('GET', '/get');

    // Sets the X-Foo header to "test", which prevents the default header
    // from being applied.
    $client->request('GET', '/get', ['headers' => ['X-Foo' => 'test']]);

    // Will disable adding in default headers.
    $client->request('GET', '/get', ['headers' => null]);

    // Will not overwrite the X-Foo header because it is in the message.
    use GuzzleHttp\Psr7\Request;
    $request = new Request('GET', 'http://foo.com', ['X-Foo' => 'test']);
    $client->send($request);

    // Will overwrite the X-Foo header with the request option provided in the
    // send method.
    use GuzzleHttp\Psr7\Request;
    $request = new Request('GET', 'http://foo.com', ['X-Foo' => 'test']);
    $client->send($request, ['headers' => ['X-Foo' => 'overwrite']]);


.. _http-errors-option:

http_errors
-----------

:Summary: Set to ``false`` to disable throwing exceptions on an HTTP protocol
    errors (i.e., 4xx and 5xx responses). Exceptions are thrown by default when
    HTTP protocol errors are encountered.
:Types: bool
:Default: ``true``
:Constant: ``GuzzleHttp\RequestOptions::HTTP_ERRORS``

.. code-block:: php

    $client->request('GET', '/status/500');
    // Throws a GuzzleHttp\Exception\ServerException

    $res = $client->request('GET', '/status/500', ['http_errors' => false]);
    echo $res->getStatusCode();
    // 500

.. warning::

    This option only has an effect if your handler has the
    ``GuzzleHttp\Middleware::httpErrors`` middleware. This middleware is added
    by default when a client is created with no handler, and is added by
    default when creating a handler with ``GuzzleHttp\default_handler``.


json
----

:Summary: The ``json`` option is used to easily upload JSON encoded data as the
    body of a request. A Content-Type header of ``application/json`` will be
    added if no Content-Type header is already present on the message.
:Types:
    Any PHP type that can be operated on by PHP's ``json_encode()`` function.
:Default: None
:Constant: ``GuzzleHttp\RequestOptions::JSON``

.. code-block:: php

    $response = $client->request('PUT', '/put', ['json' => ['foo' => 'bar']]);

Here's an example of using the ``tap`` middleware to see what request is sent
over the wire.

.. code-block:: php

    use GuzzleHttp\Middleware;

    // Grab the client's handler instance.
    $clientHandler = $client->getConfig('handler');
    // Create a middleware that echoes parts of the request.
    $tapMiddleware = Middleware::tap(function ($request) {
        echo $request->getHeader('Content-Type');
        // application/json
        echo $request->getBody();
        // {"foo":"bar"}
    });

    $response = $client->request('PUT', '/put', [
        'json'    => ['foo' => 'bar'],
        'handler' => $tapMiddleware($clientHandler)
    ]);

.. note::

    This request option does not support customizing the Content-Type header
    or any of the options from PHP's `json_encode() <http://www.php.net/manual/en/function.json-encode.php>`_<commit_msg>Update request-options.rst<commit_after>===============
Request Options
===============

You can customize requests created and transferred by a client using
**request options**. Request options control various aspects of a request
including, headers, query string parameters, timeout settings, the body of a
request, and much more.

All of the following examples use the following client:

.. code-block:: php

    $client = new GuzzleHttp\Client(['base_uri' => 'http://httpbin.org']);


.. _allow_redirects-option:

allow_redirects
---------------

:Summary: Describes the redirect behavior of a request
:Types:
        - bool
        - array
:Default:

    ::

        [
            'max'             => 5,
            'strict'          => false,
            'referer'         => false,
            'protocols'       => ['http', 'https'],
            'track_redirects' => false
        ]

:Constant: ``GuzzleHttp\RequestOptions::ALLOW_REDIRECTS``

Set to ``false`` to disable redirects.

.. code-block:: php

    $res = $client->request('GET', '/redirect/3', ['allow_redirects' => false]);
    echo $res->getStatusCode();
    // 302

Set to ``true`` (the default setting) to enable normal redirects with a maximum
number of 5 redirects.

.. code-block:: php

    $res = $client->request('GET', '/redirect/3');
    echo $res->getStatusCode();
    // 200

You can also pass an associative array containing the following key value
pairs:

- max: (int, default=5) maximum number of allowed redirects.
- strict: (bool, default=false) Set to true to use strict redirects.
  Strict RFC compliant redirects mean that POST redirect requests are sent as
  POST requests vs. doing what most browsers do which is redirect POST requests
  with GET requests.
- referer: (bool, default=false) Set to true to enable adding the Referer
  header when redirecting.
- protocols: (array, default=['http', 'https']) Specified which protocols are
  allowed for redirect requests.
- on_redirect: (callable) PHP callable that is invoked when a redirect
  is encountered. The callable is invoked with the original request and the
  redirect response that was received. Any return value from the on_redirect
  function is ignored.
- track_redirects: (bool) When set to ``true``, each redirected URI encountered
  will be tracked in the ``X-Guzzle-Redirect-History`` header in the order in
  which the redirects were encountered.

.. code-block:: php

    use Psr\Http\Message\RequestInterface;
    use Psr\Http\Message\ResponseInterface;
    use Psr\Http\Message\UriInterface;

    $onRedirect = function(
        RequestInterface $request,
        ResponseInterface $response,
        UriInterface $uri
    ) {
        echo 'Redirecting! ' . $request->getUri() . ' to ' . $uri . "\n";
    };

    $res = $client->request('GET', '/redirect/3', [
        'allow_redirects' => [
            'max'             => 10,        // allow at most 10 redirects.
            'strict'          => true,      // use "strict" RFC compliant redirects.
            'referer'         => true,      // add a Referer header
            'protocols'       => ['https'], // only allow https URLs
            'on_redirect'     => $onRedirect,
            'track_redirects' => true
        ]
    ]);

    echo $res->getStatusCode();
    // 200

    echo $res->getHeaderLine('X-Guzzle-Redirect-History');
    // http://first-redirect, http://second-redirect, etc...

.. warning::

    This option only has an effect if your handler has the
    ``GuzzleHttp\Middleware::redirect`` middleware. This middleware is added
    by default when a client is created with no handler, and is added by
    default when creating a handler with ``GuzzleHttp\default_handler``.


auth
----

:Summary: Pass an array of HTTP authentication parameters to use with the
        request. The array must contain the username in index [0], the password in
        index [1], and you can optionally provide a built-in authentication type in
        index [2]. Pass ``null`` to disable authentication for a request.
:Types:
        - array
        - string
        - null
:Default: None
:Constant: ``GuzzleHttp\RequestOptions::AUTH``

The built-in authentication types are as follows:

basic
    Use `basic HTTP authentication <http://www.ietf.org/rfc/rfc2069.txt>`_
    in the ``Authorization`` header (the default setting used if none is
    specified).

.. code-block:: php

    $client->request('GET', '/get', ['auth' => ['username', 'password']]);

digest
    Use `digest authentication <http://www.ietf.org/rfc/rfc2069.txt>`_
    (must be supported by the HTTP handler).

.. code-block:: php

    $client->request('GET', '/get', [
        'auth' => ['username', 'password', 'digest']
    ]);

.. note::

    This is currently only supported when using the cURL handler, but
    creating a replacement that can be used with any HTTP handler is
    planned.


body
----

:Summary: The ``body`` option is used to control the body of an entity
    enclosing request (e.g., PUT, POST, PATCH).
:Types:
    - string
    - ``fopen()`` resource
    - ``Psr\Http\Message\StreamInterface``
:Default: None
:Constant: ``GuzzleHttp\RequestOptions::BODY``

This setting can be set to any of the following types:

- string

  .. code-block:: php

      // You can send requests that use a string as the message body.
      $client->request('PUT', '/put', ['body' => 'foo']);

- resource returned from ``fopen()``

  .. code-block:: php

      // You can send requests that use a stream resource as the body.
      $resource = fopen('http://httpbin.org', 'r');
      $client->request('PUT', '/put', ['body' => $resource]);

- ``Psr\Http\Message\StreamInterface``

  .. code-block:: php

      // You can send requests that use a Guzzle stream object as the body
      $stream = GuzzleHttp\Psr7\stream_for('contents...');
      $client->request('POST', '/post', ['body' => $stream]);

.. note::

    This option cannot be used with ``form_params``, ``multipart``, or ``json``


.. _cert-option:

cert
----

:Summary: Set to a string to specify the path to a file containing a PEM
        formatted client side certificate. If a password is required, then set to
        an array containing the path to the PEM file in the first array element
        followed by the password required for the certificate in the second array
        element.
:Types:
        - string
        - array
:Default: None
:Constant: ``GuzzleHttp\RequestOptions::CERT``

.. code-block:: php

    $client->request('GET', '/', ['cert' => ['/path/server.pem', 'password']]);


.. _cookies-option:

cookies
-------

:Summary: Specifies whether or not cookies are used in a request or what cookie
        jar to use or what cookies to send.
:Types: ``GuzzleHttp\Cookie\CookieJarInterface``
:Default: None
:Constant: ``GuzzleHttp\RequestOptions::COOKIES``

You must specify the cookies option as a
``GuzzleHttp\Cookie\CookieJarInterface`` or ``false``.

.. code-block:: php

    $jar = new \GuzzleHttp\Cookie\CookieJar();
    $client->request('GET', '/get', ['cookies' => $jar]);

.. warning::

    This option only has an effect if your handler has the
    ``GuzzleHttp\Middleware::cookies`` middleware. This middleware is added
    by default when a client is created with no handler, and is added by
    default when creating a handler with ``GuzzleHttp\default_handler``.

.. tip::

    When creating a client, you can set the default cookie option to ``true``
    to use a shared cookie session associated with the client.


.. _connect_timeout-option:

connect_timeout
---------------

:Summary: Float describing the number of seconds to wait while trying to connect
        to a server. Use ``0`` to wait indefinitely (the default behavior).
:Types: float
:Default: ``0``
:Constant: ``GuzzleHttp\RequestOptions::CONNECT_TIMEOUT``

.. code-block:: php

    // Timeout if the client fails to connect to the server in 3.14 seconds.
    $client->request('GET', '/delay/5', ['connect_timeout' => 3.14]);

.. note::

    This setting must be supported by the HTTP handler used to send a request.
    ``connect_timeout`` is currently only supported by the built-in cURL
    handler.


.. _debug-option:

debug
-----

:Summary: Set to ``true`` or set to a PHP stream returned by ``fopen()`` to
    enable debug output with the handler used to send a request. For example,
    when using cURL to transfer requests, cURL's verbose of ``CURLOPT_VERBOSE``
    will be emitted. When using the PHP stream wrapper, stream wrapper
    notifications will be emitted. If set to true, the output is written to
    PHP's STDOUT. If a PHP stream is provided, output is written to the stream.
:Types:
        - bool
        - ``fopen()`` resource
:Default: None
:Constant: ``GuzzleHttp\RequestOptions::DEBUG``

.. code-block:: php

    $client->request('GET', '/get', ['debug' => true]);

Running the above example would output something like the following:

::

    * About to connect() to httpbin.org port 80 (#0)
    *   Trying 172.16.17.32... * Connected to httpbin.org (172.16.17.32) port 80 (#0)
    > GET /get HTTP/1.1
    Host: httpbin.org
    User-Agent: Guzzle/4.0 curl/7.21.4 PHP/5.5.7

    < HTTP/1.1 200 OK
    < Access-Control-Allow-Origin: *
    < Content-Type: application/json
    < Date: Sun, 16 Feb 2014 06:50:09 GMT
    < Server: gunicorn/0.17.4
    < Content-Length: 335
    < Connection: keep-alive
    <
    * Connection #0 to host httpbin.org left intact


.. _decode_content-option:

decode_content
--------------

:Summary: Specify whether or not ``Content-Encoding`` responses (gzip,
    deflate, etc.) are automatically decoded.
:Types:
        - string
        - bool
:Default: ``true``
:Constant: ``GuzzleHttp\RequestOptions::DECODE_CONTENT``

This option can be used to control how content-encoded response bodies are
handled. By default, ``decode_content`` is set to true, meaning any gzipped
or deflated response will be decoded by Guzzle.

When set to ``false``, the body of a response is never decoded, meaning the
bytes pass through the handler unchanged.

.. code-block:: php

    // Request gzipped data, but do not decode it while downloading
    $client->request('GET', '/foo.js', [
        'headers'        => ['Accept-Encoding' => 'gzip'],
        'decode_content' => false
    ]);

When set to a string, the bytes of a response are decoded and the string value
provided to the ``decode_content`` option is passed as the ``Accept-Encoding``
header of the request.

.. code-block:: php

    // Pass "gzip" as the Accept-Encoding header.
    $client->request('GET', '/foo.js', ['decode_content' => 'gzip']);


.. _delay-option:

delay
-----

:Summary: The number of milliseconds to delay before sending the request.
:Types:
    - integer
    - float
:Default: null
:Constant: ``GuzzleHttp\RequestOptions::DELAY``


.. _expect-option:

expect
------

:Summary: Controls the behavior of the "Expect: 100-Continue" header.
:Types:
    - bool
    - integer
:Default: ``1048576``
:Constant: ``GuzzleHttp\RequestOptions::EXPECT``

Set to ``true`` to enable the "Expect: 100-Continue" header for all requests
that sends a body. Set to ``false`` to disable the "Expect: 100-Continue"
header for all requests. Set to a number so that the size of the payload must
be greater than the number in order to send the Expect header. Setting to a
number will send the Expect header for all requests in which the size of the
payload cannot be determined or where the body is not rewindable.

By default, Guzzle will add the "Expect: 100-Continue" header when the size of
the body of a request is greater than 1 MB and a request is using HTTP/1.1.

.. note::

    This option only takes effect when using HTTP/1.1. The HTTP/1.0 and
    HTTP/2.0 protocols do not support the "Expect: 100-Continue" header.
    Support for handling the "Expect: 100-Continue" workflow must be
    implemented by Guzzle HTTP handlers used by a client.


force_ip_resolve
----------------

:Summary: Set to "v4" if you want the HTTP handlers to use only ipv4 protocol or "v6" for ipv6 protocol.
:Types: string
:Default: null
:Constant: ``GuzzleHttp\RequestOptions::FORCE_IP_RESOLVE``

.. code-block:: php

    // Force ipv4 protocol
    $client->request('GET', '/foo', ['force_ip_resolve' => 'v4']);

    // Force ipv6 protocol
    $client->request('GET', '/foo', ['force_ip_resolve' => 'v6']);

.. note::

    This setting must be supported by the HTTP handler used to send a request.
    ``force_ip_resolve`` is currently only supported by the built-in cURL
    handler.


form_params
-----------

:Summary: Used to send an `application/x-www-form-urlencoded` POST request.
:Types: array
:Constant: ``GuzzleHttp\RequestOptions::FORM_PARAMS``

Associative array of form field names to values where each value is a string or
array of strings. Sets the Content-Type header to
application/x-www-form-urlencoded when no Content-Type header is already
present.

.. code-block:: php

    $client->request('POST', '/post', [
        'form_params' => [
            'foo' => 'bar',
            'baz' => ['hi', 'there!']
        ]
    ]);

.. note::

    ``form_params`` cannot be used with the ``multipart`` option. You will need to use
    one or the other. Use ``form_params`` for ``application/x-www-form-urlencoded``
    requests, and ``multipart`` for ``multipart/form-data`` requests.

    This option cannot be used with ``body``, ``multipart``, or ``json``


headers
-------

:Summary: Associative array of headers to add to the request. Each key is the
    name of a header, and each value is a string or array of strings
    representing the header field values.
:Types: array
:Defaults: None
:Constant: ``GuzzleHttp\RequestOptions::HEADERS``

.. code-block:: php

    // Set various headers on a request
    $client->request('GET', '/get', [
        'headers' => [
            'User-Agent' => 'testing/1.0',
            'Accept'     => 'application/json',
            'X-Foo'      => ['Bar', 'Baz']
        ]
    ]);

Headers may be added as default options when creating a client. When headers
are used as default options, they are only applied if the request being created
does not already contain the specific header. This include both requests passed
to the client in the ``send()`` and ``sendAsync()`` methods and requests
created by the client (e.g., ``request()`` and ``requestAsync()``).

.. code-block:: php

    $client = new GuzzleHttp\Client(['headers' => ['X-Foo' => 'Bar']]);

    // Will send a request with the X-Foo header.
    $client->request('GET', '/get');

    // Sets the X-Foo header to "test", which prevents the default header
    // from being applied.
    $client->request('GET', '/get', ['headers' => ['X-Foo' => 'test']]);

    // Will disable adding in default headers.
    $client->request('GET', '/get', ['headers' => null]);

    // Will not overwrite the X-Foo header because it is in the message.
    use GuzzleHttp\Psr7\Request;
    $request = new Request('GET', 'http://foo.com', ['X-Foo' => 'test']);
    $client->send($request);

    // Will overwrite the X-Foo header with the request option provided in the
    // send method.
    use GuzzleHttp\Psr7\Request;
    $request = new Request('GET', 'http://foo.com', ['X-Foo' => 'test']);
    $client->send($request, ['headers' => ['X-Foo' => 'overwrite']]);


.. _http-errors-option:

http_errors
-----------

:Summary: Set to ``false`` to disable throwing exceptions on an HTTP protocol
    errors (i.e., 4xx and 5xx responses). Exceptions are thrown by default when
    HTTP protocol errors are encountered.
:Types: bool
:Default: ``true``
:Constant: ``GuzzleHttp\RequestOptions::HTTP_ERRORS``

.. code-block:: php

    $client->request('GET', '/status/500');
    // Throws a GuzzleHttp\Exception\ServerException

    $res = $client->request('GET', '/status/500', ['http_errors' => false]);
    echo $res->getStatusCode();
    // 500

.. warning::

    This option only has an effect if your handler has the
    ``GuzzleHttp\Middleware::httpErrors`` middleware. This middleware is added
    by default when a client is created with no handler, and is added by
    default when creating a handler with ``GuzzleHttp\default_handler``.


json
----

:Summary: The ``json`` option is used to easily upload JSON encoded data as the
    body of a request. A Content-Type header of ``application/json`` will be
    added if no Content-Type header is already present on the message.
:Types:
    Any PHP type that can be operated on by PHP's ``json_encode()`` function.
:Default: None
:Constant: ``GuzzleHttp\RequestOptions::JSON``

.. code-block:: php

    $response = $client->request('PUT', '/put', ['json' => ['foo' => 'bar']]);

Here's an example of using the ``tap`` middleware to see what request is sent
over the wire.

.. code-block:: php

    use GuzzleHttp\Middleware;

    // Grab the client's handler instance.
    $clientHandler = $client->getConfig('handler');
    // Create a middleware that echoes parts of the request.
    $tapMiddleware = Middleware::tap(function ($request) {
        echo $request->getHeaderLine('Content-Type');
        // application/json
        echo $request->getBody();
        // {"foo":"bar"}
    });

    $response = $client->request('PUT', '/put', [
        'json'    => ['foo' => 'bar'],
        'handler' => $tapMiddleware($clientHandler)
    ]);

.. note::

    This request option does not support customizing the Content-Type header
    or any of the options from PHP's `json_encode() <http://www.php.net/manual/en/function.json-encode.php>`_
{'fraction_non_alphanumeric': 0.1327668311043942, 'fraction_numerical': 0.008953776839944111, 'mean_word_length': 3.0282563749138527, 'pattern_counts': {'":': 2, '<': 25, '<?xml version=': 0, '>': 185, 'https://': 0, 'lorem ipsum': 0, 'www.': 12, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7357137', 'n_tokens_mistral': 10438, 'n_tokens_neox': 9886, 'n_words': 3908}