Permalink
Browse files

Merge pull request #346 from adamlundrigan/fix/http

Refactor Zend\Http documentation
  • Loading branch information...
2 parents 0a61bb2 + 7488e12 commit 548f1b5661861f32a1472842ded96250bb453deb @Freeaqingme Freeaqingme committed Oct 13, 2012
View
4 docs/languages/en/index.rst
@@ -89,10 +89,10 @@
modules/zend.http.request
modules/zend.http.response
modules/zend.http.headers
- modules/zend.http.cookie.handling
modules/zend.http.client
modules/zend.http.client.adapters
modules/zend.http.client.advanced
+ modules/zend.http.client-static
modules/zend.i18n.translating
modules/zend.i18n.view.helpers
modules/zend.i18n.filters
@@ -376,10 +376,10 @@ Zend\\Http
* :doc:`modules/zend.http.request`
* :doc:`modules/zend.http.response`
* :doc:`modules/zend.http.headers`
- * :doc:`modules/zend.http.cookie.handling`
* :doc:`modules/zend.http.client`
* :doc:`modules/zend.http.client.adapters`
* :doc:`modules/zend.http.client.advanced`
+ * :doc:`modules/zend.http.client-static`
.. _zend.i18n:
View
75 docs/languages/en/modules/zend.http.client-static.rst
@@ -0,0 +1,75 @@
+.. _zend.http.client-static:
+
+HTTP Client - Static Usage
+==========================
+
+.. _zend.http.client-static.intro:
+
+Overview
+--------
+
+The ``Zend\Http`` component also provides ``Zend\Http\ClientStatic``, a static
+HTTP client which exposes a simplified API for quickly performing GET and POST
+operations:
+
+.. _zend.http.client-static.quick-start:
+
+Quick Start
+-----------
+
+.. code-block:: php
+ :linenos:
+
+ use Zend\Http\Client;
+
+ // Simple GET request
+ $response = ClientStatic::get('http://example.org')
+
+ // More complex GET request, specifying query string 'foo=bar' and adding a
+ // custom header to request JSON data be returned (Accept: application/json)
+ $response = ClientStatic::get(
+ 'http://example.org',
+ array( 'foo' => 'bar' ),
+ array( 'Accept' => 'application/json')
+ );
+
+ // We can also do a POST request using the same format. Here we POST
+ // login credentials (username/password) to a login page:
+ $response = ClientStatic::post('https://example.org/login.php', array(
+ 'username' => 'foo',
+ 'password' => 'bar',
+ ));
+
+
+Configuration Options
+---------------------
+
+It is not possible to set configuration options on the ``Zend\Http\Client`` instance
+encapsulated by ``Zend\Http\ClientStatic``. To perform a HTTP request which requires
+non-default configurations, please use ``Zend\Http\Client`` directly.
+
+.. _zend.http.client-static.methods:
+
+Available Methods
+-----------------
+
+.. _zend.http.client-static.methods.get:
+
+**get**
+ ``get(string $url, array $query = array(), array $headers = array(), mixed $body = null)``
+
+ Perform an HTTP ``GET`` request using the provided URL, query string variables, headers
+ and request body.
+
+ Returns Zend\\Http\\Response
+
+.. _zend.http.client-static.methods.post:
+
+**post**
+ ``post(string $url, array $params, array $headers = array(), mixed $body = null)``
+
+ Perform an HTTP ``POST`` request using the provided URL, parameters, headers
+ and request body.
+
+ Returns Zend\\Http\\Response
+
View
183 docs/languages/en/modules/zend.http.client.adapters.rst
@@ -1,69 +1,75 @@
.. _zend.http.client.adapters:
-Zend_Http_Client - Connection Adapters
-======================================
+HTTP Client - Connection Adapters
+=================================
.. _zend.http.client.adapters.overview:
Overview
--------
-``Zend_Http_Client`` is based on a connection adapter design. The connection adapter is the object in charge of
+``Zend\Http\Client`` is based on a connection adapter design. The connection adapter is the object in charge of
performing the actual connection to the server, as well as writing requests and reading responses. This connection
adapter can be replaced, and you can create and extend the default connection adapters to suite your special needs,
without the need to extend or replace the entire *HTTP* client class, and with the same interface.
-Currently, the ``Zend_Http_Client`` class provides four built-in connection adapters:
+Currently, the ``Zend\Http\Client`` class provides four built-in connection adapters:
- - ``Zend_Http_Client_Adapter_Socket`` (default)
+- ``Zend\Http\Client\Adapter\Socket`` (default)
- - ``Zend_Http_Client_Adapter_Proxy``
+- ``Zend\Http\Client\Adapter\Proxy``
- - ``Zend_Http_Client_Adapter_Curl``
+- ``Zend\Http\Client\Adapter\Curl``
- - ``Zend_Http_Client_Adapter_Test``
+- ``Zend\Http\Client\Adapter\Test``
-The ``Zend_Http_Client`` object's adapter connection adapter is set using the 'adapter' configuration option. When
+The ``Zend\Http\Client`` object's adapter connection adapter is set using the 'adapter' configuration option. When
instantiating the client object, you can set the 'adapter' configuration option to a string containing the
-adapter's name (eg. 'Zend_Http_Client_Adapter_Socket') or to a variable holding an adapter object (eg. ``new
-Zend_Http_Client_Adapter_Test``). You can also set the adapter later, using the ``Zend_Http_Client->setConfig()``
+adapter's name (eg. 'Zend\\Http\\Client\\Adapter\\Socket') or to a variable holding an adapter object (eg. ``new
+Zend\Http\Client\Adapter\Socket``). You can also set the adapter later, using the ``Zend\Http\Client->setAdapter()``
method.
.. _zend.http.client.adapters.socket:
The Socket Adapter
------------------
-The default connection adapter is the ``Zend_Http_Client_Adapter_Socket`` adapter - this adapter will be used
+The default connection adapter is the ``Zend\Http\Client\Adapter\Socket`` adapter - this adapter will be used
unless you explicitly set the connection adapter. The Socket adapter is based on *PHP*'s built-in fsockopen()
function, and does not require any special extensions or compilation flags.
The Socket adapter allows several extra configuration options that can be set using
-``Zend_Http_Client->setConfig()`` or passed to the client constructor.
+``Zend\Http\Client->setOptions()`` or passed to the client constructor.
.. _zend.http.client.adapter.socket.configuration.table:
- .. table:: Zend_Http_Client_Adapter_Socket configuration parameters
-
- +-------------+------------------------------------------------------------------------------------+-------------+-------------+
- |Parameter |Description |Expected Type|Default Value|
- +=============+====================================================================================+=============+=============+
- |persistent |Whether to use persistent TCP connections |boolean |FALSE |
- +-------------+------------------------------------------------------------------------------------+-------------+-------------+
- |ssltransport |SSL transport layer (eg. 'sslv2', 'tls') |string |ssl |
- +-------------+------------------------------------------------------------------------------------+-------------+-------------+
- |sslcert |Path to a PEM encoded SSL certificate |string |NULL |
- +-------------+------------------------------------------------------------------------------------+-------------+-------------+
- |sslpassphrase|Passphrase for the SSL certificate file |string |NULL |
- +-------------+------------------------------------------------------------------------------------+-------------+-------------+
- |sslusecontext|Enables proxied connections to use SSL even if the proxy connection itself does not.|boolean |FALSE |
- +-------------+------------------------------------------------------------------------------------+-------------+-------------+
+ .. table:: Zend\\Http\\Client\\Adapter\\Socket configuration parameters
+
+ +-------------------+------------------------------------------------------------------------------------+-------------+-------------+
+ |Parameter |Description |Expected Type|Default Value|
+ +===================+====================================================================================+=============+=============+
+ |persistent |Whether to use persistent TCP connections |boolean |FALSE |
+ +-------------------+------------------------------------------------------------------------------------+-------------+-------------+
+ |ssltransport |SSL transport layer (eg. 'sslv2', 'tls') |string |ssl |
+ +-------------------+------------------------------------------------------------------------------------+-------------+-------------+
+ |sslcert |Path to a PEM encoded SSL certificate |string |NULL |
+ +-------------------+------------------------------------------------------------------------------------+-------------+-------------+
+ |sslpassphrase |Passphrase for the SSL certificate file |string |NULL |
+ +-------------------+------------------------------------------------------------------------------------+-------------+-------------+
+ |sslverifypeer |Whether to verify the SSL peer |string |NULL |
+ +-------------------+------------------------------------------------------------------------------------+-------------+-------------+
+ |sslcapath |Path to SSL certificate directory |string |NULL |
+ +-------------------+------------------------------------------------------------------------------------+-------------+-------------+
+ |sslallowselfsigned |Whether to allow self-signed certificates |string |NULL |
+ +-------------------+------------------------------------------------------------------------------------+-------------+-------------+
+ |sslusecontext |Enables proxied connections to use SSL even if the proxy connection itself does not.|boolean |FALSE |
+ +-------------------+------------------------------------------------------------------------------------+-------------+-------------+
@@ -106,15 +112,15 @@ The Socket adapter allows several extra configuration options that can be set us
// Set the configuration parameters
$config = array(
- 'adapter' => 'Zend_Http_Client_Adapter_Socket',
+ 'adapter' => 'Zend\Http\Client\Adapter\Socket',
'ssltransport' => 'tls'
);
// Instantiate a client object
- $client = new Zend_Http_Client('https://www.example.com', $config);
+ $client = new Zend\Http\Client('https://www.example.com', $config);
// The following request will be sent over a TLS secure connection.
- $response = $client->request();
+ $response = $client->send();
The result of the example above will be similar to opening a *TCP* connection using the following *PHP* command:
@@ -125,11 +131,11 @@ The result of the example above will be similar to opening a *TCP* connection us
Customizing and accessing the Socket adapter stream context
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Starting from Zend Framework 1.9, ``Zend_Http_Client_Adapter_Socket`` provides direct access to the underlying
+``Zend\Http\Client\Adapter\Socket`` provides direct access to the underlying
`stream context`_ used to connect to the remote server. This allows the user to pass specific options and
parameters to the *TCP* stream, and to the *SSL* wrapper in case of *HTTPS* connections.
-You can access the stream context using the following methods of ``Zend_Http_Client_Adapter_Socket``:
+You can access the stream context using the following methods of ``Zend\Http\Client\Adapter\Socket``:
@@ -169,8 +175,8 @@ You can access the stream context using the following methods of ``Zend_Http_Cli
);
// Create an adapter object and attach it to the HTTP client
- $adapter = new Zend_Http_Client_Adapter_Socket();
- $client = new Zend_Http_Client();
+ $adapter = new Zend\Http\Client\Adapter\Socket();
+ $client = new Zend\Http\Client();
$client->setAdapter($adapter);
// Method 1: pass the options array to setStreamContext()
@@ -185,7 +191,7 @@ You can access the stream context using the following methods of ``Zend_Http_Cli
stream_context_set_option($context, $options);
// Now, perform the request
- $response = $client->request();
+ $response = $client->send();
// If everything went well, you can now access the context again
$opts = stream_context_get_options($adapter->getStreamContext());
@@ -203,9 +209,9 @@ You can access the stream context using the following methods of ``Zend_Http_Cli
The Proxy Adapter
-----------------
-The ``Zend_Http_Client_Adapter_Proxy`` adapter is similar to the default Socket adapter - only the connection is
+The ``Zend\Http\Client\Adapter\Proxy`` adapter is similar to the default Socket adapter - only the connection is
made through an *HTTP* proxy server instead of a direct connection to the target server. This allows usage of
-``Zend_Http_Client`` behind proxy servers - which is sometimes needed for security or performance reasons.
+``Zend\Http\Client`` behind proxy servers - which is sometimes needed for security or performance reasons.
Using the Proxy adapter requires several additional configuration parameters to be set, in addition to the default
'adapter' option:
@@ -227,51 +233,51 @@ Using the Proxy adapter requires several additional configuration parameters to
+----------+------------------------------+-------------+--------------------------------------+
|proxy_pass|Proxy password, if required |string |'secret' or '' for none (default) |
+----------+------------------------------+-------------+--------------------------------------+
- |proxy_auth|Proxy HTTP authentication type|string |Zend_Http_Client::AUTH_BASIC (default)|
+ |proxy_auth|Proxy HTTP authentication type|string |Zend\Http\Client::AUTH_BASIC (default)|
+----------+------------------------------+-------------+--------------------------------------+
-proxy_host should always be set - if it is not set, the client will fall back to a direct connection using
-``Zend_Http_Client_Adapter_Socket``. proxy_port defaults to '8080' - if your proxy listens on a different port you
+``proxy_host`` should always be set - if it is not set, the client will fall back to a direct connection using
+``Zend\Http\Client\Adapter\Socket``. ``proxy_port`` defaults to '8080' - if your proxy listens on a different port you
must set this one as well.
-proxy_user and proxy_pass are only required if your proxy server requires you to authenticate. Providing these will
-add a 'Proxy-Authentication' header to the request. If your proxy does not require authentication, you can leave
-these two options out.
+``proxy_user`` and ``proxy_pass`` are only required if your proxy server requires you to authenticate. Providing
+these will add a 'Proxy-Authentication' header to the request. If your proxy does not require authentication, you
+can leave these two options out.
-proxy_auth sets the proxy authentication type, if your proxy server requires authentication. Possibly values are
-similar to the ones accepted by the Zend_Http_Client::setAuth() method. Currently, only basic authentication
-(Zend_Http_Client::AUTH_BASIC) is supported.
+``proxy_auth`` sets the proxy authentication type, if your proxy server requires authentication. Possibly values are
+similar to the ones accepted by the ``Zend\Http\Client::setAuth()`` method. Currently, only basic authentication
+(``Zend\Http\Client::AUTH_BASIC``) is supported.
.. _zend.http.client.adapters.proxy.example-1:
-.. rubric:: Using Zend_Http_Client behind a proxy server
+.. rubric:: Using Zend\\Http\\Client behind a proxy server
.. code-block:: php
:linenos:
// Set the configuration parameters
$config = array(
- 'adapter' => 'Zend_Http_Client_Adapter_Proxy',
+ 'adapter' => 'Zend\Http\Client\Adapter\Proxy',
'proxy_host' => 'proxy.int.zend.com',
'proxy_port' => 8000,
'proxy_user' => 'shahar.e',
'proxy_pass' => 'bananashaped'
);
// Instantiate a client object
- $client = new Zend_Http_Client('http://www.example.com', $config);
+ $client = new Zend\Http\Client('http://www.example.com', $config);
// Continue working...
-As mentioned, if proxy_host is not set or is set to a blank string, the connection will fall back to a regular
+As mentioned, if ``proxy_host`` is not set or is set to a blank string, the connection will fall back to a regular
direct connection. This allows you to easily write your application in a way that allows a proxy to be used
optionally, according to a configuration parameter.
.. note::
- Since the proxy adapter inherits from ``Zend_Http_Client_Adapter_Socket``, you can use the stream context access
+ Since the proxy adapter inherits from ``Zend\Http\Client\Adapter\Socket``, you can use the stream context access
method (see :ref:`this section <zend.http.client.adapters.socket.streamcontext>`) to set stream context options
on Proxy connections as demonstrated above.
@@ -293,10 +299,10 @@ mechanisms and shines in applications that move large files around between serve
:linenos:
$config = array(
- 'adapter' => 'Zend_Http_Client_Adapter_Curl',
+ 'adapter' => 'Zend\Http\Client\Adapter\Curl',
'curloptions' => array(CURLOPT_FOLLOWLOCATION => true),
);
- $client = new Zend_Http_Client($uri, $config);
+ $client = new Zend\Http\Client($uri, $config);
By default the cURL adapter is configured to behave exactly like the Socket Adapter and it also accepts the same
configuration parameters as the Socket and Proxy adapters. You can also change the cURL options by either
@@ -316,16 +322,17 @@ You can use cURL to transfer very large files over *HTTP* by filehandle.
$putFileSize = filesize("filepath");
$putFileHandle = fopen("filepath", "r");
- $adapter = new Zend_Http_Client_Adapter_Curl();
- $client = new Zend_Http_Client();
+ $adapter = new Zend\Http\Client\Adapter\Curl();
+ $client = new Zend\Http\Client();
$client->setAdapter($adapter);
- $adapter->setConfig(array(
+ $client->setMethod('PUT');
+ $adapter->setOptions(array(
'curloptions' => array(
CURLOPT_INFILE => $putFileHandle,
CURLOPT_INFILESIZE => $putFileSize
)
));
- $client->request("PUT");
+ $client->send();
.. _zend.http.client.adapters.test:
@@ -335,13 +342,13 @@ The Test Adapter
Sometimes, it is very hard to test code that relies on *HTTP* connections. For example, testing an application that
pulls an *RSS* feed from a remote server will require a network connection, which is not always available.
-For this reason, the ``Zend_Http_Client_Adapter_Test`` adapter is provided. You can write your application to use
-``Zend_Http_Client``, and just for testing purposes, for example in your unit testing suite, you can replace the
+For this reason, the ``Zend\Http\Client\Adapter\Test`` adapter is provided. You can write your application to use
+``Zend\Http\Client``, and just for testing purposes, for example in your unit testing suite, you can replace the
default adapter with a Test adapter (a mock object), allowing you to run tests without actually performing server
connections.
-The ``Zend_Http_Client_Adapter_Test`` adapter provides an additional method, setResponse() method. This method
-takes one parameter, which represents an *HTTP* response as either text or a ``Zend_Http_Response`` object. Once
+The ``Zend\Http\Client\Adapter\Test`` adapter provides an additional method, ``setResponse()``. This method
+takes one parameter, which represents an *HTTP* response as either text or a ``Zend\Http\Response`` object. Once
set, your Test adapter will always return this response, without even performing an actual *HTTP* request.
.. _zend.http.client.adapters.test.example-1:
@@ -352,8 +359,8 @@ set, your Test adapter will always return this response, without even performing
:linenos:
// Instantiate a new adapter and client
- $adapter = new Zend_Http_Client_Adapter_Test();
- $client = new Zend_Http_Client('http://www.example.com', array(
+ $adapter = new Zend\Http\Client\Adapter\Test();
+ $client = new Zend\Http\Client('http://www.example.com', array(
'adapter' => $adapter
));
@@ -372,7 +379,7 @@ set, your Test adapter will always return this response, without even performing
// and so on...
'</rss>');
- $response = $client->request('GET');
+ $response = $client->send();
// .. continue parsing $response..
The above example shows how you can preset your *HTTP* client to return the response you need. Then, you can
@@ -391,8 +398,8 @@ your program might need before returning to the caller.
:linenos:
// Instantiate a new adapter and client
- $adapter = new Zend_Http_Client_Adapter_Test();
- $client = new Zend_Http_Client('http://www.example.com', array(
+ $adapter = new Zend\Http\Client\Adapter\Test();
+ $client = new Zend\Http\Client('http://www.example.com', array(
'adapter' => $adapter
));
@@ -420,23 +427,23 @@ your program might need before returning to the caller.
// 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 ``Zend_Http_Client_Adapter_Test``'s buffer and sets the first
-response that will be returned. The addResponse() method will add successive responses.
+The ``setResponse()`` method clears any responses in the ``Zend\Http\Client\Adapter\Test``'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()
+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.
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`` exception. This can be useful when
-your application caches content from an external site (in case the site goes down) and you want to test this
-feature.
+next call to ``connect()`` to throw an ``Zend\Http\Client\Adapter\Exception\RuntimeException`` exception. 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.
.. _zend.http.client.adapters.test.example-3:
@@ -446,18 +453,18 @@ feature.
:linenos:
// Instantiate a new adapter and client
- $adapter = new Zend_Http_Client_Adapter_Test();
- $client = new Zend_Http_Client('http://www.example.com', array(
+ $adapter = new Zend\Http\Client\Adapter\Test();
+ $client = new Zend\Http\Client('http://www.example.com', array(
'adapter' => $adapter
));
// Force the next request to fail with an exception
$adapter->setNextRequestWillFail(true);
try {
- // This call will result in a Zend_Http_Client_Adapter_Exception
+ // This call will result in a Zend\Http\Client\Adapter\Exception\RuntimeException
$client->request();
- } catch (Zend_Http_Client_Adapter_Exception $e) {
+ } catch (Zend\Http\Client\Adapter\Exception\RuntimeException $e) {
// ...
}
@@ -469,12 +476,12 @@ feature.
Creating your own connection adapters
-------------------------------------
-You can create your own connection adapters and use them. 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.
+``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 the
-``Zend_Http_Client_Adapter_Interface`` interface. The following example shows the skeleton of a user-implemented
+``Zend\Http\Client\Adapter\AdapterInterface`` interface. 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:
.. _zend.http.client.adapters.extending.example-1:
@@ -484,18 +491,18 @@ adapter class. All the public functions defined in this example must be defined
.. code-block:: php
:linenos:
- class MyApp_Http_Client_Adapter_BananaProtocol
- implements Zend_Http_Client_Adapter_Interface
+ class MyApp\Http\Client\Adapter\BananaProtocol
+ implements Zend\Http\Client\Adapter\AdapterInterface
{
/**
- * Set the configuration array for the adapter
+ * Set Adapter Options
*
* @param array $config
*/
- public function setConfig($config = array())
+ public function setOptions($config = array())
{
// This rarely changes - you should usually copy the
- // implementation in Zend_Http_Client_Adapter_Socket.
+ // implementation in Zend\Http\Client\Adapter\Socket.
}
/**
@@ -552,8 +559,8 @@ adapter class. All the public functions defined in this example must be defined
}
// Then, you could use this adapter:
- $client = new Zend_Http_Client(array(
- 'adapter' => 'MyApp_Http_Client_Adapter_BananaProtocol'
+ $client = new Zend\Http\Client(array(
+ 'adapter' => 'MyApp\Http\Client\Adapter\BananaProtocol'
));
View
385 docs/languages/en/modules/zend.http.client.advanced.rst
@@ -1,162 +1,194 @@
.. _zend.http.client.advanced:
-Zend_Http_Client - Advanced Usage
-=================================
+HTTP Client - Advanced Usage
+============================
.. _zend.http.client.redirections:
HTTP Redirections
-----------------
-By default, ``Zend_Http_Client`` automatically handles *HTTP* redirections, and will follow up to 5 redirections.
-This can be changed by setting the 'maxredirects' configuration parameter.
+``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
+always use a ``GET`` request when redirecting. By default, ``Zend\Http\Client`` does the same - when redirecting on
a 301 or 302 response, all ``GET`` and POST 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
+location. This behavior can be changed by setting the ``strictredirects`` configuration parameter to boolean
``TRUE``:
+.. _zend.http.client.redirections.example-1:
+.. rubric:: Forcing RFC 2616 Strict Redirections on 301 and 302 Responses
- .. _zend.http.client.redirections.example-1:
-
- .. rubric:: Forcing RFC 2616 Strict Redirections on 301 and 302 Responses
-
- .. code-block:: php
- :linenos:
+.. code-block:: php
+ :linenos:
- // Strict Redirections
- $client->setConfig(array('strictredirects' => true));
+ // Strict Redirections
+ $client->setOptions(array('strictredirects' => true));
- // Non-strict Redirections
- $client->setConfig(array('strictredirects' => false));
+ // Non-strict Redirections
+ $client->setOptions(array('strictredirects' => false));
-You can always get the number of redirections done after sending a request using the getRedirectionsCount() method.
+You can always get the number of redirections done after sending a request using the ``getRedirectionsCount()`` method.
.. _zend.http.client.cookies:
Adding Cookies and Using Cookie Persistence
-------------------------------------------
-``Zend_Http_Client`` provides an easy interface for adding cookies to your request, so that no direct header
-modification is required. This is done using the setCookie() method. This method can be used in several ways:
+``Zend\Http\Client`` provides an easy 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. The
+``addCookie`` method has a number of operating modes:
+.. _zend.http.client.cookies.example-1:
+.. rubric:: Setting Cookies Using addCookie()
- .. _zend.http.client.cookies.example-1:
+.. code-block:: php
+ :linenos:
- .. rubric:: Setting Cookies Using setCookie()
+ // Easy and simple: by providing a cookie name and cookie value
+ $client->addCookie('flavor', 'chocolate chips');
- .. code-block:: php
- :linenos:
+ // By directly providing a raw cookie string (name=value)
+ // Note that the value must be already URL encoded
+ $client->addCookie('flavor=chocolate%20chips');
- // Easy and simple: by providing a cookie name and cookie value
- $client->setCookie('flavor', 'chocolate chips');
+ // By providing a Zend\Http\Header\SetCookie object
+ $cookie = Zend\Http\Header\SetCookie::fromString('flavor=chocolate%20chips');
+ $client->addCookie($cookie);
- // By directly providing a raw cookie string (name=value)
- // Note that the value must be already URL encoded
- $client->setCookie('flavor=chocolate%20chips');
+ // Multiple cookies can be set at once by providing an
+ // array of Zend\Http\Header\SetCookie objects
+ $cookies = array(
+ Zend\Http\Header\SetCookie::fromString('flavorOne=chocolate%20chips'),
+ Zend\Http\Header\SetCookie::fromString('flavorTwo=vanilla'),
+ );
+ $client->addCookie($cookies);
- // By providing a Zend_Http_Cookie object
- $cookie = Zend_Http_Cookie::fromString('flavor=chocolate%20chips');
- $client->setCookie($cookie);
+The ``setCookies()`` method works in a similar manner, except that it requires an array
+of cookie values as its only argument and also clears the cookie container before
+adding the new cookies:
-For more information about ``Zend_Http_Cookie`` objects, see :ref:`this section <zend.http.cookies>`.
+.. _zend.http.client.cookies.example-2:
-``Zend_Http_Client`` also provides the means for cookie stickiness - that is having the client internally store all
-sent and received cookies, and resend them automatically on subsequent requests. This is useful, for example when
-you need to log in to a remote site first and receive and authentication or session ID cookie before sending
-further requests.
+.. rubric:: Setting Cookies Using setCookies()
+.. code-block:: php
+ :linenos:
+ // setCookies accepts an array of cookie values, which
+ // can be in either of the following formats:
+ $client->setCookies(array(
- .. _zend.http.client.cookies.example-2:
+ // A raw cookie string (name=value)
+ // Note that the value must be already URL encoded
+ 'flavor=chocolate%20chips',
- .. rubric:: Enabling Cookie Stickiness
+ // A Zend\Http\Header\SetCookie object
+ Zend\Http\Header\SetCookie::fromString('flavor=chocolate%20chips'),
- .. code-block:: php
- :linenos:
+ ));
- // To turn cookie stickiness on, set a Cookie Jar
- $client->setCookieJar();
- // First request: log in and start a session
- $client->setUri('http://example.com/login.php');
- $client->setParameterPost('user', 'h4x0r');
- $client->setParameterPost('password', '1337');
- $client->request('POST');
+For more information about ``Zend\Http\Header\SetCookie`` objects, see :ref:`this section <zend.http.header.set-cookie>`.
- // The Cookie Jar automatically stores the cookies set
- // in the response, like a session ID cookie.
+``Zend\Http\Client`` also provides a means for simplifying cookie stickiness - that is having the client internally store all
+sent and received cookies, and resend them on subsequent requests: ``Zend\Http\Client\Cookies``. This is useful, for example when
+you need to log in to a remote site first and receive and authentication or session ID cookie before sending
+further requests.
- // Now we can send our next request - the stored cookies
- // will be automatically sent.
- $client->setUri('http://example.com/read_member_news.php');
- $client->request('GET');
+.. _zend.http.client.cookies.example-3:
-For more information about the ``Zend_Http_CookieJar`` class, see :ref:`this section
-<zend.http.cookies.cookiejar>`.
+.. rubric:: Enabling Cookie Stickiness
-.. _zend.http.client.custom_headers:
+.. code-block:: php
+ :linenos:
-Setting Custom Request Headers
-------------------------------
+ $cookies = new Zend\Http\Cookies();
+
+ // First request: log in and start a session
+ $client->setUri('http://example.com/login.php');
+ $client->setParameterPost(array('user' => 'h4x0r'));
+ $client->setParameterPost(array('password' => 'l33t'));
+ $response = $client->request('POST');
+ $cookies->addCookiesFromResponse($response, $client->getUri());
-Setting custom headers can be done by using the setHeaders() method. This method is quite diverse and can be used
-in several ways, as the following example shows:
+ // Now we can send our next request
+ $client->setUri('http://example.com/read_member_news.php');
+ $client->addCookies($cookies->getMatchingCookies($client->getUri());
+ $client->request('GET');
+For more information about the ``Zend\Http\Client\Cookies`` class, see :ref:`this section
+<zend.http.client.cookies>`.
+.. _zend.http.client.custom_headers:
- .. _zend.http.client.custom_headers.example-1:
+Setting Custom Request Headers
+------------------------------
- .. rubric:: Setting A Single Custom Request Header
+Setting custom headers is performed by first fetching the header container from the client's
+``Zend\Http\Request`` object. This method is quite diverse and can be used in several ways,
+as the following example shows:
- .. code-block:: php
- :linenos:
+.. _zend.http.client.custom_headers.example-1:
- // Setting a single header, overwriting any previous value
- $client->setHeaders('Host', 'www.example.com');
+.. rubric:: Setting A Single Custom Request Header
- // Another way of doing the exact same thing
- $client->setHeaders('Host: www.example.com');
+.. code-block:: php
+ :linenos:
- // Setting several values for the same header
- // (useful mostly for Cookie headers):
- $client->setHeaders('Cookie', array(
- 'PHPSESSID=1234567890abcdef1234567890abcdef',
- 'language=he'
- ));
+ // Fetch the container
+ $headers = $client->getRequest()->getHeaders();
+ // Setting a single header. Will not overwrite any
+ // previously-added headers of the same name.
+ $client->addHeaderLine('Host', 'www.example.com');
+ // Another way of doing the exact same thing
+ $client->addHeaderLine('Host: www.example.com');
-setHeader() can also be easily used to set multiple headers in one call, by providing an array of headers as a
-single parameter:
+ // Another way of doing the exact same thing using
+ // the provided Zend\Http\Header class
+ $client->addHeader(Zend\Http\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:
+ $client->addHeaders(array(
+ // Zend\Http\Header\* object
+ Zend\Http\Header\Host::fromString('Host: www.example.com'),
+ // Header name as array key, header value as array key value
+ 'Cookie' => 'PHPSESSID=1234567890abcdef1234567890abcdef',
- .. _zend.http.client.custom_headers.example-2:
+ // Raw header string
+ 'Cookie: language=he',
+ ));
- .. rubric:: Setting Multiple Custom Request Headers
- .. code-block:: php
- :linenos:
+``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 it's ``Zend\Http\Request`` object. As a consequence, any pre-existing headers
+will be erased.
- // Setting multiple headers, overwriting any previous value
- $client->setHeaders(array(
- 'Host' => 'www.example.com',
- 'Accept-encoding' => 'gzip,deflate',
- 'X-Powered-By' => 'Zend Framework'));
+.. _zend.http.client.custom_headers.example-2:
- // The array can also contain full array strings:
- $client->setHeaders(array(
- 'Host: www.example.com',
- 'Accept-encoding: gzip,deflate',
- 'X-Powered-By: Zend Framework'));
+.. rubric:: Setting Multiple Custom Request Headers
+.. code-block:: php
+ :linenos:
+
+ // Setting multiple headers. Will remove all existing
+ // headers and add new ones to the Request header container
+ $client->setHeaders(array(
+ Zend\Http\Header\Host::fromString('Host: www.example.com'),
+ 'Accept-encoding' => 'gzip,deflate',
+ 'X-Powered-By: Zend Framework'
+ ));
.. _zend.http.client.file_uploads:
@@ -166,78 +198,75 @@ 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
+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 >input< 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
+``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.
+.. _zend.http.client.file_uploads.example-1:
- .. _zend.http.client.file_uploads.example-1:
+.. rubric:: Using setFileUpload to Upload Files
- .. rubric:: Using setFileUpload to Upload Files
-
- .. code-block:: php
- :linenos:
+.. code-block:: php
+ :linenos:
- // Uploading arbitrary data as a file
- $text = 'this is some plain text';
- $client->setFileUpload('some_text.txt', 'upload', $text, 'text/plain');
+ // 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');
+ // Uploading an existing file
+ $client->setFileUpload('/tmp/Backup.tar.gz', 'bufile');
- // Send the files
- $client->request('POST');
+ // 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 guesses automatically if possible - and if not, the content type will
+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 - and if not, the content type will
be set to 'application/octet-stream'.
.. note::
**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 requests body on
+ 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.
.. _zend.http.client.raw_post_data:
Sending Raw POST Data
---------------------
-You can use a ``Zend_Http_Client`` to send raw POST data using the setRawData() method. This method takes two
-parameters: the first is the data to send in the request body. The second optional parameter is the content-type of
-the data. While this parameter is optional, you should usually set it before sending the request - either using
-setRawData(), or with another method: setEncType().
-
-
+You can use a ``Zend\Http\Client`` to send raw POST data 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()``.
- .. _zend.http.client.raw_post_data.example-1:
- .. rubric:: Sending Raw POST Data
+.. _zend.http.client.raw_post_data.example-1:
- .. code-block:: php
- :linenos:
+.. rubric:: Sending Raw POST Data
- $xml = '<book>' .
- ' <title>Islands in the Stream</title>' .
- ' <author>Ernest Hemingway</author>' .
- ' <year>1970</year>' .
- '</book>';
-
- $client->setRawData($xml, 'text/xml')->request('POST');
+.. code-block:: php
+ :linenos:
- // Another way to do the same thing:
- $client->setRawData($xml)->setEncType('text/xml')->request('POST');
+ $xml = '<book>' .
+ ' <title>Islands in the Stream</title>' .
+ ' <author>Ernest Hemingway</author>' .
+ ' <year>1970</year>' .
+ '</book>';
+ $client->setMethod('POST');
+ $client->setRawBody($xml);
+ $client->setEncType('text/xml');
+ $client->send();
-The data should be available on the server side through *PHP*'s $HTTP_RAW_POST_DATA variable or through the
-php://input stream.
+The data should be available on the server side through *PHP*'s ``$HTTP_RAW_POST_DATA`` variable or through the
+``php://input`` stream.
.. note::
@@ -252,28 +281,27 @@ php://input stream.
HTTP Authentication
-------------------
-Currently, ``Zend_Http_Client`` only supports basic *HTTP* authentication. This feature is utilized using the
+Currently, ``Zend\Http\Client`` only supports basic *HTTP* authentication. This feature is utilized using the
``setAuth()`` method, or by specifying a username and a password in the URI. The ``setAuth()`` method takes 3
parameters: The user name, the password and an optional authentication type parameter. As mentioned, currently only
basic authentication is supported (digest authentication support is planned).
+.. _zend.http.client.http_authentication.example-1:
- .. _zend.http.client.http_authentication.example-1:
+.. rubric:: Setting HTTP Authentication User and Password
- .. rubric:: Setting HTTP Authentication User and Password
-
- .. code-block:: php
- :linenos:
+.. code-block:: php
+ :linenos:
- // Using basic authentication
- $client->setAuth('shahar', 'myPassword!', Zend_Http_Client::AUTH_BASIC);
+ // Using basic authentication
+ $client->setAuth('shahar', 'myPassword!', Zend_Http_Client::AUTH_BASIC);
- // Since basic auth is default, you can just do this:
- $client->setAuth('shahar', 'myPassword!');
+ // Since basic auth is default, you can just do this:
+ $client->setAuth('shahar', 'myPassword!');
- // You can also specify username and password in the URI
- $client->setUri('http://christer:secret@example.com');
+ // You can also specify username and password in the URI
+ $client->setUri('http://christer:secret@example.com');
@@ -282,7 +310,7 @@ basic authentication is supported (digest authentication support is planned).
Sending Multiple Requests With the Same Client
----------------------------------------------
-``Zend_Http_Client`` was also designed specifically to handle several consecutive requests with the same object.
+``Zend\Http\Client`` was also designed specifically to handle several consecutive requests with the same object.
This is useful in cases where a script requires data to be fetched from several places, or when accessing a
specific *HTTP* resource requires logging in and obtaining a session cookie, for example.
@@ -292,26 +320,24 @@ once all requests are done and the Client object is destroyed. This prevents the
*TCP* connections to the server.
When you perform several requests with the same client, but want to make sure all the request-specific parameters
-are cleared, you should use the resetParameters() method. This ensures that ``GET`` and POST parameters, request
-body and request-specific headers are reset and are not reused in the next request.
+are cleared, you should use the ``resetParameters()`` method. This ensures that GET and POST parameters, request
+body and headers are reset and are not reused in the next request.
.. note::
**Resetting parameters**
- Note that non-request specific headers are not reset by default when the ``resetParameters()`` method is used.
- Only the 'Content-length' and 'Content-type' headers are reset. This allows you to set-and-forget headers like
- 'Accept-language' and 'Accept-encoding'
+ Note that cookies are not reset by default when the ``resetParameters()`` method is used.
+ To clean all cookies as well, use ``resetParameters(true)``, or call ``clearCookies()`` after
+ calling ``resetParameters()``.
- To clean all headers and other data except for URI and method, use ``resetParameters(true)``.
-
-Another feature designed specifically for consecutive requests is the Cookie Jar object. Cookie Jars allow you to
-automatically save cookies set by the server in the first request, and send them on consecutive requests
-transparently. This allows, for example, going through an authentication request before sending the actual data
-fetching request.
+Another feature designed specifically for consecutive requests is the ``Zend\Http\Client\Cookies`` object.
+This "Cookie Jar" allow you to save cookies set by the server in a request, and send them back on consecutive
+requests transparently. This allows, for example, going through an authentication request before sending
+the actual data-fetching request.
If your application requires one authentication request per user, and consecutive requests might be performed in
-more than one script in your application, it might be a good idea to store the Cookie Jar object in the user's
+more than one script in your application, it might be a good idea to store the Cookies object in the user's
session. This way, you will only need to authenticate the user once every session.
.. _zend.http.client.multiple_requests.example-1:
@@ -322,24 +348,24 @@ session. This way, you will only need to authenticate the user once every sessio
:linenos:
// First, instantiate the client
- $client = new Zend_Http_Client('http://www.example.com/fetchdata.php', array(
+ $client = new Zend\Http\Client('http://www.example.com/fetchdata.php', array(
'keepalive' => true
));
// Do we have the cookies stored in our session?
if (isset($_SESSION['cookiejar']) &&
- $_SESSION['cookiejar'] instanceof Zend_Http_CookieJar) {
+ $_SESSION['cookiejar'] instanceof Zend\Http\Client\Cookies) {
- $client->setCookieJar($_SESSION['cookiejar']);
+ $cookieJar = $_SESSION['cookiejar'];
} else {
// If we don't, authenticate and store cookies
- $client->setCookieJar();
$client->setUri('http://www.example.com/login.php');
$client->setParameterPost(array(
'user' => 'shahar',
'pass' => 'somesecret'
));
- $client->request(Zend_Http_Client::POST);
+ $response = $client->setMethod('POST')->send();
+ $cookieJar = Zend\Http\Client\Cookies::fromResponse($response);
// Now, clear parameters and set the URI to the original one
// (note that the cookies that were set by the server are now
@@ -348,45 +374,27 @@ session. This way, you will only need to authenticate the user once every sessio
$client->setUri('http://www.example.com/fetchdata.php');
}
- $response = $client->request(Zend_Http_Client::GET);
+ // Add the cookies to the new request
+ $client->setCookies($cookieJar->getMatchingCookies($client->getUri()));
+ $response = $client->setMethod('GET')->send();
// Store cookies in session, for next page
- $_SESSION['cookiejar'] = $client->getCookieJar();
+ $_SESSION['cookiejar'] = $cookieJar;
.. _zend.http.client.streaming:
Data Streaming
--------------
-By default, ``Zend_Http_Client`` accepts and returns data as *PHP* strings. However, in many cases there are big
-files to be sent or received, thus keeping them in memory might be unnecessary or too expensive. For these cases,
-``Zend_Http_Client`` supports reading data from files (and in general, *PHP* streams) and writing data to files
-(streams).
-
-In order to use stream to pass data to ``Zend_Http_Client``, use ``setRawData()`` method with data argument being
-stream resource (e.g., result of ``fopen()``).
-
-
-
- .. _zend.http.client.streaming.example-1:
-
- .. rubric:: Sending file to HTTP server with streaming
-
- .. code-block:: php
- :linenos:
-
- $fp = fopen("mybigfile.zip", "r");
- $client->setRawData($fp, 'application/zip')->request('PUT');
-
-
-
-Only PUT requests currently support sending streams to *HTTP* server.
+By default, ``Zend\Http\Client`` accepts and returns data as *PHP* strings. However, in many cases there are big
+files to be received, thus keeping them in memory might be unnecessary or too expensive. For these cases,
+``Zend\Http\Client`` supports writing data to files (streams).
In order to receive data from the server as stream, use ``setStream()``. Optional argument specifies the filename
where the data will be stored. If the argument is just ``TRUE`` (default), temporary file will be used and will be
deleted once response object is destroyed. Setting argument to ``FALSE`` disables the streaming functionality.
-When using streaming, ``request()`` method will return object of class ``Zend_Http_Client_Response_Stream``, which
+When using streaming, ``send()`` method will return object of class ``Zend\Http\Response\Stream``, which
has two useful methods: ``getStreamName()`` will return the name of the file where the response is stored, and
``getStream()`` will return stream from which the response could be read.
@@ -403,15 +411,12 @@ write it to another file using regular stream functions.
:linenos:
$client->setStream(); // will use temp file
- $response = $client->request('GET');
+ $response = $client->send();
// copy file
copy($response->getStreamName(), "my/downloads/file");
// use stream
$fp = fopen("my/downloads/file2", "w");
stream_copy_to_stream($response->getStream(), $fp);
// Also can write to known file
- $client->setStream("my/downloads/myfile)->request('GET');
-
-
-
+ $client->setStream("my/downloads/myfile")->send();
View
174 docs/languages/en/modules/zend.http.client.rst
@@ -1,7 +1,7 @@
.. _zend.http.client:
-Zend\\Http\\Client
-==================
+HTTP Client - Overview
+======================
.. _zend.http.client.intro:
@@ -35,28 +35,26 @@ be left out, and set later using the setUri() and setConfig() methods.
// This is actually exactly the same:
$client = new Client();
$client->setUri('http://example.org');
- $client->setConfig(array(
+ $client->setOptions(array(
'maxredirects' => 0,
'timeout' => 30
));
- // You can also use a Zend\Config\Ini object to set the client's configuration
- $config = new Zend\Config\Ini('httpclient.ini', 'secure');
- $client->setConfig($config);
+ // You can also pass a Zend\Config\Config object to set the client's configuration
+ $config = Zend\Config\Factory::fromFile('httpclient.ini');
+ $client->setOptions($config);
.. note::
- ``Zend\Http\Client`` uses ``Zend\Uri\Http`` to validate URLs. This means that some special characters like the
- pipe symbol ('\|') or the caret symbol ('^') will not be accepted in the URL by default. This can be modified by
- setting the 'allowunwise' option of ``Zend\Uri`` to '``TRUE``'. See :ref:`this section
- <zend.uri.validation.allowunwise>` for more information.
+ ``Zend\Http\Client`` uses ``Zend\Uri\Http`` to validate URLs. See the :ref:`Zend\\Uri manual page<zend.uri>`
+ for more information on the validation process.
.. _zend.http.client.options:
Configuration Options
---------------------
-The constructor and setConfig() method accept an associative array of configuration parameters, or a
+The constructor and setOptions() method accept an associative array of configuration parameters, or a
``Zend\Config\Config`` object. Setting these parameters is optional, as they all have default values.
@@ -70,8 +68,6 @@ The constructor and setConfig() method accept an associative array of configurat
+===============+====================================================================================================================================================================================+===============+=====================================+
|maxredirects |Maximum number of redirections to follow (0 = none) |integer |5 |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+-------------------------------------+
- |strict |Whether perform validation on header names. When set to FALSE, validation functions will be skipped. Usually this should not be changed |boolean |TRUE |
- +---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+-------------------------------------+
|strictredirects|Whether to strictly follow the RFC when redirecting (see this section) |boolean |FALSE |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+-------------------------------------+
|useragent |User agent identifier string (sent in request headers) |string |'Zend\\Http\\Client' |
@@ -88,8 +84,10 @@ The constructor and setConfig() method accept an associative array of configurat
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+-------------------------------------+
|encodecookies |Whether to pass the cookie value through urlencode/urldecode. Enabling this breaks support with some web servers. Disabling this limits the range of values the cookies can contain.|boolean |TRUE |
+---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+-------------------------------------+
-
-
+ |outputstream |Destination for streaming of received data (options: string (filename), true for temp file, false/null to disable streaming) |boolean |FALSE |
+ +---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+-------------------------------------+
+ |rfc3986strict |Whether to strictly adhere to RFC 3986 (in practice, this means replacing '+' with '%20') |boolean |FALSE |
+ +---------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+---------------+-------------------------------------+
.. _zend.http.client.methods:
@@ -99,23 +97,21 @@ Available Methods
.. _zend.http.client.methods.__construct:
**__construct**
- ``__construct(string $uri, array $config)``
+ ``__construct(string $uri, array|Traversable $config)``
Constructor
Returns void
-.. _zend.http.client.methods.set-config:
+.. _zend.http.client.methods.set-options:
-**setConfig**
- ``setConfig(Config|array $config = array ( ))``
+**setOptions**
+ ``setOptions(array|Traversable $config = array ())``
Set configuration parameters for this HTTP client
-
-
Returns Zend\\Http\\Client
.. _zend.http.client.methods.set-adapter:
@@ -125,86 +121,72 @@ Available Methods
Load the connection adapter
- While this method is not called more than one for a client, it is seperated from ->send() to preserve logic
+ While this method is not called more than once for a client, it is seperated from ->send() to preserve logic
and readability
- Returns null
+ Returns Zend\\Http\\Client
.. _zend.http.client.methods.get-adapter:
**getAdapter**
``getAdapter()``
- Load the connection adapter
+ Retrieve the connection adapter
+ Returns Zend\\Http\\Client\\Adapter\\AdapterInterface
+.. _zend.http.client.methods.set-request:
- Returns Zend\\Http\\Client\\Adapter
+**setRequest**
+ ``setRequest(Zend\Http\Zend\Http\Request $request)``
+
+ Set request object
+
+ Returns void
.. _zend.http.client.methods.get-request:
**getRequest**
``getRequest()``
- Get Request
-
-
-
- Returns Request
-
-.. _zend.http.client.methods.get-response:
-
-**getResponse**
- ``getResponse()``
-
- Get Response
+ Get Request object
+ Returns Zend\\Http\\Request
+.. _zend.http.client.methods.get-last-raw-request:
- Returns Response
-
-.. _zend.http.client.methods.set-request:
-
-**setRequest**
- ``setRequest(Zend\Http\Zend\Http\Request $request)``
-
- Set request
-
+**getLastRawRequest**
+ ``getLastRawRequest()``
+ Get the last request (as a string)
- Returns void
+ Returns string
.. _zend.http.client.methods.set-response:
**setResponse**
- ``setResponse(Zend\Http\Zend\Http\Response $response)``
+ ``setResponse(Zend\Http\Response $response)``
Set response
+ Returns Zend\\Http\\Client
+.. _zend.http.client.methods.get-response:
- Returns void
-
-.. _zend.http.client.methods.get-last-request:
-
-**getLastRequest**
- ``getLastRequest()``
-
- Get the last request (as a string)
-
+**getResponse**
+ ``getResponse()``
+ Get Response object
- Returns string
+ Returns Zend\\Http\\Response
-.. _zend.http.client.methods.get-last-response:
+.. _zend.http.client.methods.get-last-raw-response:
-**getLastResponse**
- ``getLastResponse()``
+**getLastRawResponse**
+ ``getLastRawResponse()``
Get the last response (as a string)
-
-
Returns string
.. _zend.http.client.methods.get-redirections-count:
@@ -214,8 +196,6 @@ Available Methods
Get the redirections count
-
-
Returns integer
.. _zend.http.client.methods.set-uri:
@@ -225,9 +205,7 @@ Available Methods
Set Uri (to the request)
-
-
- Returns void
+ Returns Zend\\Http\\Client
.. _zend.http.client.methods.get-uri:
@@ -236,9 +214,7 @@ Available Methods
Get uri (from the request)
-
-
- Returns Zend\\Http\\Zend\\Uri\\Http
+ Returns Zend\\Uri\\Http
.. _zend.http.client.methods.set-method:
@@ -247,8 +223,6 @@ Available Methods
Set the HTTP method (to the request)
-
-
Returns Zend\\Http\\Client
.. _zend.http.client.methods.get-method:
@@ -258,8 +232,6 @@ Available Methods
Get the HTTP method
-
-
Returns string
.. _zend.http.client.methods.set-enc-type:
@@ -269,8 +241,6 @@ Available Methods
Set the encoding type and the boundary (if any)
-
-
Returns void
.. _zend.http.client.methods.get-enc-type:
@@ -280,8 +250,6 @@ Available Methods
Get the encoding type
-
-
Returns type
.. _zend.http.client.methods.set-raw-body:
@@ -291,8 +259,6 @@ Available Methods
Set raw body (for advanced use cases)
-
-
Returns Zend\\Http\\Client
.. _zend.http.client.methods.set-parameter-post:
@@ -302,8 +268,6 @@ Available Methods
Set the POST parameters
-
-
Returns Zend\\Http\\Client
.. _zend.http.client.methods.set-parameter-get:
@@ -313,8 +277,6 @@ Available Methods
Set the GET parameters
-
-
Returns Zend\\Http\\Client
.. _zend.http.client.methods.get-cookies:
@@ -324,19 +286,15 @@ Available Methods
Return the current cookies
-
-
Returns array
.. _zend.http.client.methods.add-cookie:
**addCookie**
- ``addCookie(ArrayIterator|SetCookie|string $cookie, string $value, string $domain, string $expire, string $path, boolean $secure = false, boolean $httponly = true)``
+ ``addCookie(ArrayIterator|SetCookie|string $cookie, string $value = null, string $expire = null, string $path = null, string $domain = null, boolean $secure = false, boolean $httponly = true, string $maxAge = null, string $version = null)``
Add a cookie
-
-
Returns Zend\\Http\\Client
.. _zend.http.client.methods.set-cookies:
@@ -439,10 +397,22 @@ Available Methods
Returns void
+.. _zend.http.client.methods.dispatch:
+
+**dispatch**
+ ``dispatch(Zend\Stdlib\RequestInterface $request, Zend\Stdlib\ResponseInterface $response= null)``
+
+ Dispatch HTTP request
+
+
+
+ Returns Response
+
+
.. _zend.http.client.methods.send:
**send**
- ``send(Request $request)``
+ ``send(Zend\Http\Request $request)``
Send HTTP request
@@ -453,7 +423,7 @@ Available Methods
.. _zend.http.client.methods.set-file-upload:
**setFileUpload**
- ``setFileUpload(string $filename, string $formname, string $data, string $ctype)``
+ ``setFileUpload(string $filename, string $formname, string $data = null, string $ctype = null)``
Set a file to upload (using a POST request)
@@ -478,7 +448,7 @@ Available Methods
.. _zend.http.client.methods.encode-form-data:
**encodeFormData**
- ``encodeFormData(string $boundary, string $name, mixed $value, string $filename, array $headers = array ( ))``
+ ``encodeFormData(string $boundary, string $name, mixed $value, string $filename = null, array $headers = array ( ))``
Encode data to a multipart/form-data part suitable for a POST request.
@@ -524,9 +494,6 @@ called, the default request method is ``GET`` (see the above example).
use Zend\Http\Client;
$client = new Client();
// Performing a POST request
- $response = $client->send('POST');
-
- // Yet another way of performing a POST request
$client->setMethod(Client::POST);
$response = $client->send();
@@ -535,20 +502,15 @@ called, the default request method is ``GET`` (see the above example).
.. rubric:: Adding GET and POST 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`` parameter's name as its first
-parameter, and the ``GET`` parameter's value as its second parameter. For convenience, the setParameterGet() method
-can also accept a single associative array of name => value ``GET`` variables - which may be more comfortable when
-several ``GET`` parameters need to be set.
+of the URL, or by using the setParameterGet() method. This method takes the ``GET`` parameters as an associative
+array of name => value ``GET`` variables.
.. code-block:: php
:linenos:
use Zend\Http\Client;
$client = new Client();
- // Setting a get parameter using the setParameterGet method
- $client->setParameterGet('knight', 'lancelot');
-
// This is equivalent to setting such URL:
$client->setUri('http://example.com/index.php?knight=lancelot');
@@ -572,8 +534,6 @@ the setParameterPost() method, which is similar to the setParameterGet() method
use Zend\Http\Client;
$client = new Client();
- // Setting a POST parameter
- $client->setParameterPost('language', 'fr');
// Setting several POST parameters, one of them with several values
$client->setParameterPost(array(
@@ -600,7 +560,7 @@ POST request, POST parameters are simply ignored.
$request = new Request();
$request->setUri('http://www.test.com');
$request->setMethod('POST');
- $request->setParameterPost(array('foo' => 'bar'));
+ $request->getPost()->set('foo', 'bar');
$client = new Client();
$response = $client->dispatch($request);
@@ -613,4 +573,4 @@ POST request, POST parameters are simply ignored.
.. _`http://www.w3.org/Protocols/rfc2616/rfc2616.html`: http://www.w3.org/Protocols/rfc2616/rfc2616.html
-.. [#] See RFC 2616 -`http://www.w3.org/Protocols/rfc2616/rfc2616.html`_.
+.. [#] See RFC 2616 -`http://www.w3.org/Protocols/rfc2616/rfc2616.html`_.
View
174 docs/languages/en/modules/zend.http.headers.rst
@@ -1,15 +1,15 @@
.. _zend.http.headers:
-Zend\\Http\\Headers And The Various Header Classes
-==================================================
+The Headers Class
+=================
.. _zend.http.headers.intro:
Overview
--------
The ``Zend\Http\Headers`` class is a container for HTTP headers. It is typically accessed as part of a
-``Zend\Http\Request`` or ``Zend\Http\Response`` ``header()`` call. The Headers container will lazily load actual
+``Zend\Http\Request`` or ``Zend\Http\Response`` ``getHeaders()`` call. The Headers container will lazily load actual
Header objects as to reduce the overhead of header specific parsing.
The ``Zend\Http\Header\*`` classes are the domain specific implementations for the various types of Headers that
@@ -25,12 +25,45 @@ Quick Start
The quickest way to get started interacting with header objects is by getting an already populated Headers
container from a request or response object.
+.. code-block:: php
+ :linenos:
+
+ // $client is an instance of Zend\Http\Client
+
+ // You can retrieve the request headers by first retrieving
+ // the Request object and then calling getHeaders on it
+ $requestHeaders = $client->getRequest()->getHeaders();
+
+ // The same method also works for retrieving Response headers
+ $responseHeaders = $client->getResponse()->getHeaders();
+
+``Zend\Http\Headers`` can also extract headers from a string:
+
+.. code-block:: php
+ :linenos:
+
+ $headerString = <<<EOB
+ Host: www.example.com
+ Content-Type: text/html
+ Content-Length: 1337
+ EOB;
+
+ $headers = Zend\Http\Headers::fromString($headerString);
+ // $headers is now populated with three objects
+ // (1) Zend\Http\Header\Host
+ // (2) Zend\Http\Header\ContentType
+ // (3) Zend\Http\Header\ContentLength
+
+Now that you have an instance of ``Zend\Http\Headers`` you can manipulate the individual headers it contains using
+the provided public API methods outlined in the ":ref:`Available Methods<zend.http.headers.methods>`" section.
+
+
.. _zend.http.headers.options:
Configuration Options
---------------------
-None currently available.
+No configuration options are available.
.. _zend.http.headers.methods:
@@ -80,7 +113,7 @@ Available Methods
.. _zend.http.headers.methods.add-header-line:
-**addHeaders**
+**addHeaderLine**
``addHeaderLine(string $headerFieldNameOrLine, string $fieldValue)``
Add a raw header line, either in name => value, or as a single string 'name: value'
@@ -97,8 +130,6 @@ Available Methods
Add a Header to this container, for raw values see ``addHeaderLine()`` and ``addHeaders()``.
-
-
Returns ``Zend\Http\Headers``
.. _zend.http.headers.methods.remove-header:
@@ -128,8 +159,6 @@ Available Methods
Get all headers of a certain name/type
-
-
Returns false| ``Zend\Http\Header\HeaderInterface``\ | ``ArrayIterator``
.. _zend.http.headers.methods.has:
@@ -226,13 +255,6 @@ Available Methods
Returns bool
-.. _zend.http.headers.examples:
-
-Examples
---------
-
-
-
.. _zend.http.headers.header-description:
Zend\\Http\\Header\\* Base Methods
@@ -278,7 +300,7 @@ Zend\\Http\\Header\\* Base Methods
.. _zend.http.header-types.list:
-List of Http Header Types
+List of HTTP Header Types
-------------------------
.. table:: Zend\\Http\\Header\\* Classes
@@ -324,7 +346,8 @@ List of Http Header Types
+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|ContentType |N/A |
+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- |Cookie |Extends \\ArrayObjectsetEncodeValue() / getEncodeValue() - Whether or not to encode values |
+ |Cookie |Extends \\ArrayObject |
+ | |setEncodeValue() / getEncodeValue() - Whether or not to encode values |
+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|Date |N/A |
+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -372,7 +395,18 @@ List of Http Header Types
+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|Server |N/A |
+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- |SetCookie |getName() / setName() - The cookies namegetValue() / setValue() - The cookie valuegetDomain() / setDomain() - The domain the cookie applies togetExpires() / setExpires() - The time frame the cookie is valid for, null is a session cookiegetPath() / setPath() - The uri path the cookie is bound toisSecure() / setSecure() - Whether the cookies contains the Secure flagisHttponly() / setHttponly() - Whether the cookies can be accessed via HTTP only|
+ |SetCookie |getName() / setName() - The cookie name |
+ | |getValue() / setValue() - The cookie value |
+ | |getExpires() / setExpires() - The time frame the cookie is valid for, null is a session cookie |
+ | |getPath() / setPath() - The uri path the cookie is bound to |
+ | |getDomain() / setDomain() - The domain the cookie applies to |
+ | |getMaxAge() / setMaxAge() - The maximum age of the cookie |
+ | |getVersion() / setVersion() - The cookie version |
+ | |isSecure() / setSecure() - Whether the cookies contains the Secure flag |
+ | |isHttponly() / setHttponly() - Whether the cookies can be accessed via HTTP only |
+ | |isSessionCookie() - Whether the cookie is a session cookie |
+ | |isExpired() - Whether the cookie is expired |
+ | |isValidForRequest() - Whether the cookie is valid for a given request domain, path and isSecure |
+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|TE |N/A |
+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -393,4 +427,106 @@ List of Http Header Types
|WWWAuthenticate |N/A |
+------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+.. _zend.http.headers.examples:
+
+Examples
+--------
+
+.. _zend.http.headers.examples.retrieving-headers:
+
+.. rubric:: Retrieving headers from a Zend\\Http\\Headers object
+
+.. code-block:: php
+ :linenos:
+
+ // $client is an instance of Zend\Http\Client
+ $response = $client->send();
+ $headers = $response->getHeaders();
+
+ // We can check if the Request contains a specific header by
+ // using the ``has`` method. Returns boolean ``TRUE`` if at least
+ // one matching header found, and ``FALSE`` otherwise
+ $headers->has('Content-Type');
+
+ // We can retrieve all instances of a specific header by using
+ // the ``get`` method:
+ $contentTypeHeaders = $headers->get('Content-Type');
+
+There are three possibilities for the return value of the above call to the ``get`` method:
+
+ - If no Content-Type header was set in the Request, ``get`` will return false.
+
+ - If only one Content-Type header was set in the Request,
+ ``get`` will return an instance of ``Zend\Http\Header\ContentType``.
+
+ - If more than one Content-Type header was set in the Request,
+ ``get`` will return an ArrayIterator containing one
+ ``Zend\Http\Header\ContentType`` instance per header.
+
+.. _zend.http.headers.examples.adding-headers:
+
+.. rubric:: Adding headers to a Zend\\Http\\Headers object
+
+.. code-block:: php
+ :linenos:
+
+ $headers = new Zend\Http\Headers();
+
+ // We can directly add any object that implements Zend\Http\Header\HeaderInterface
+ $typeHeader = Zend\Http\Header\ContentType::fromString('Content-Type: text/html');
+ $headers->addHeader($typeHeader);
+
+ // We can add headers using the raw string representation, either
+ // passing the header name and value as separate arguments...
+ $headers->addHeaderLine('Content-Type', 'text/html');
+
+ // .. or we can pass the entire header as the only argument
+ $headers->addHeaderLine('Content-Type: text/html');
+
+ // We can also add headers in bulk using addHeaders, which accepts
+ // an array of individual header definitions that can be in any of
+ // the accepted formats outlined below:
+ $headers->addHeaders(array(
+
+ // An object implementing Zend\Http\Header\HeaderInterface
+ Zend\Http\Header\ContentType::fromString('Content-Type: text/html'),
+
+ // A raw header string
+ 'Content-Type: text/html',
+
+ // We can also pass the header name as the array key and the
+ // header content as that array key's value
+ 'Content-Type' => 'text/html');
+
+ ));
+
+.. _zend.http.headers.examples.removing-headers:
+
+.. rubric:: Removing headers from a Zend\\Http\\Headers object
+
+We can remove all headers of a specific type using the ``removeHeader`` method,
+which accepts a single object implementing ``Zend\Http\Header\HeaderInterface``
+
+.. code-block:: php
+ :linenos:
+
+ // $headers is a pre-configured instance of Zend\Http\Headers
+
+ // We can also delete individual headers or groups of headers
+ $matches = $headers->get('Content-Type');
+
+ // If more than one header was found, iterate over the collection
+ // and remove each one individually
+ if ($matches instanceof ArrayIterator) {
+ foreach ($headers as $header) {
+ $headers->removeHeader($header);
+ }
+ // If only a single header was found, remove it directly
+ } elseif ($matches instanceof Zend\Http\Header\HeaderInterface) {
+ $headers->removeHeader($header);
+ }
+
+ // In addition to this, we can clear all the headers currently stored in
+ // the container by calling the clearHeaders() method
+ $matches->clearHeaders();
View
307 docs/languages/en/modules/zend.http.request.rst
@@ -1,7 +1,7 @@
.. _zend.http.request:
-Zend\\Http\\Request
-===================
+The Request Class
+=================
.. _zend.http.request.intro:
@@ -24,10 +24,10 @@ A typical HTTP request looks like this:
| BODY |
--------------------------
-In simplified terms, the request consist of a method, *URI* and the HTTP version number which all make up the
-"Request Line." Next is a set of headers; there can be 0 or an unlimited number of headers. After that is the
-request body, which is typically used when a client wishes to send data to the server in the form of an encoded
-file, or include a set of POST parameters, for example. More information on the structure and specification of an
+In simplified terms, the request consists of a method, *URI* and HTTP version number which together make up the
+"Request Line." Next come the HTTP headers, of which there can be 0 or more. After that is the request body,
+which is typically used when a client wishes to send data to the server in the form of an encoded file,
+or include a set of POST parameters, for example. More information on the structure and specification of a
HTTP request can be found in `RFC-2616 on the W3.org site`_.
.. _zend.http.request.quick-start:
@@ -42,32 +42,35 @@ completely empty object to start with, by simply instantiating the ``Zend\Http\R
:linenos:
use Zend\Http\Request;
+
$request = Request::fromString(<<<EOS
POST /foo HTTP/1.1
- HeaderField1: header-field-value
+ \r\n
+ HeaderField1: header-field-value1
HeaderField2: header-field-value2
-
+ \r\n\r\n
foo=bar&
- EOS);
+ EOS
+ );
// OR, the completely equivalent
$request = new Request();
$request->setMethod(Request::METHOD_POST);
$request->setUri('/foo');
- $request->header()->addHeaders(array(
- 'HeaderField1' => 'header-field-value',
+ $request->getHeaders()->addHeaders(array(
+ 'HeaderField1' => 'header-field-value1',
'HeaderField2' => 'header-field-value2',
- );
- $request->post()->set('foo', 'bar');
+ ));
+ $request->getPost()->set('foo', 'bar');
.. _zend.http.request.options:
Configuration Options
---------------------
-None currently
+No configuration options are available.
.. _zend.http.request.methods:
@@ -79,7 +82,7 @@ Available Methods
**Request::fromString**
``Request::fromString(string $string)``
- A factory that produces a Request object from a well-formed Http Request string
+ A factory that produces a Request object from a well-formed HTTP Request string.
Returns ``Zend\Http\Request``
@@ -99,16 +102,16 @@ Available Methods
Return the method for this request.
- Returns string.
+ Returns string
.. _zend.http.request.methods.set-uri:
**setUri**
- ``setUri(string|\Zend\Stdlib\RequestInterface|\Zend\Stdlib\Message|\Zend\Stdlib\ParametersInterface|\Zend\Stdlib\Parameters|\Zend\Uri\Http $uri)``
+ ``setUri(string|Zend\Uri\Http $uri)``
Set the URI/URL for this request; this can be a string or an instance of ``Zend\Uri\Http``.
- Returns Zend\\Http\\Request
+ Returns ``Zend\Http\Request``
.. _zend.http.request.methods.get-uri:
@@ -117,16 +120,16 @@ Available Methods
Return the URI for this request object.
- Returns string.
+ Returns ``Zend\Uri\Http``
-.. _zend.http.request.methods.uri:
+.. _zend.http.request.methods.get-uri-string:
-**uri**
- ``uri()``
+**getUriString**
+ ``getUriString()``
- Return the URI for this request object as an instance of ``Zend\Uri\Http``.
+ Return the URI for this request object as a string.
- Returns ``Zend\Uri\Http``.
+ Returns string
.. _zend.http.request.methods.set-version:
@@ -135,14 +138,14 @@ Available Methods
Set the HTTP version for this object, one of 1.0 or 1.1 (``Request::VERSION_10``, ``Request::VERSION_11``).
- Returns ``Zend\Http\Request``.
+ Returns ``Zend\Http\Request``
.. _zend.http.request.methods.get-version:
-**setVersion**
+**getVersion**
``getVersion()``
- Return the HTTP version for this request
+ Return the HTTP version for this request.
Returns string
@@ -152,140 +155,126 @@ Available Methods
``setQuery(Zend\Stdlib\ParametersInterface $query)``
Provide an alternate Parameter Container implementation for query parameters in this object. (This is NOT the
- primary API for value setting; for that, see ``query()``.)
+ primary API for value setting; for that, see ``getQuery()``).
- Returns Zend\\Http\\Request
+ Returns ``Zend\Http\Request``
-.. _zend.http.request.methods.query:
+.. _zend.http.request.methods.get-query:
-**setQuery**
- ``query()``
+**getQuery**
+ ``getQuery(string|null $name, mixed|null $default)``
- Return the parameter container responsible for query parameters.
+ Return the parameter container responsible for query parameters or a single query parameter.
- Returns ``Zend\Stdlib\ParametersInterface``
+ Returns ``string``, ``Zend\Stdlib\ParametersInterface``, or ``null`` depending on value of ``$name`` argument.
.. _zend.http.request.methods.set-post:
**setPost**
``setPost(Zend\Stdlib\ParametersInterface $post)``
- Provide an alternate Parameter Container implementation for post parameters in this object. (This is NOT the
- primary API for value setting; for that, see ``post()``.)
+ Provide an alternate Parameter Container implementation for POST parameters in this object. (This is NOT the
+ primary API for value setting; for that, see ``getPost()``).
Returns ``Zend\Http\Request``
-.. _zend.http.request.methods.post:
+.. _zend.http.request.methods.get-post:
-**post**
- ``post()``
+**getPost**
+ ``getPost(string|null $name, mixed|null $default)``
- Return the parameter container responsible for post parameters.
+ Return the parameter container responsible for POST parameters or a single POST parameter.
- Returns ``Zend\Stdlib\ParametersInterface``
+ Returns ``string``, ``Zend\Stdlib\ParametersInterface``, or ``null`` depending on value of ``$name`` argument.
-.. _zend.http.request.methods.cookie:
+.. _zend.http.request.methods.get-cookie:
-**cookie**
- ``cookie()``
+**getCookie**
+ ``getCookie()``
- Return the Cookie header, this is the same as calling *$request->header()->get('Cookie');*.
+ Return the Cookie header, this is the same as calling *$request->getHeaders()->get('Cookie');*.
Returns ``Zend\Http\Header\Cookie``
-.. _zend.http.request.methods.set-file:
+.. _zend.http.request.methods.set-files:
-**setFile**
- ``setFile(Zend\Stdlib\ParametersInterface $files)``
+**setFiles**
+ ``setFiles(Zend\Stdlib\ParametersInterface $files)``
- Provide an alternate Parameter Container implementation for file parameters in this object. (This is NOT the
- primary API for value setting; for that, see ``file()``.)
+ Provide an alternate Parameter Container implementation for file parameters in this object, (This is NOT the
+ primary API for value setting; for that, see ``getFiles()``).
Returns ``Zend\Http\Request``
-.. _zend.http.request.methods.file:
+.. _zend.http.request.methods.get-files:
-**file**
- ``file()``
+**getFiles**
+ ``getFiles(string|null $name, mixed|null $default)``
- Return the parameter container responsible for file parameters
+ Return the parameter container responsible for file parameters or a single file parameter.
- Returns ``Zend\Stdlib\ParametersInterface``
+ Returns ``string``, ``Zend\Stdlib\ParametersInterface``, or ``null`` depending on value of ``$name`` argument.
-.. _zend.http.request.methods.set-server:
+.. _zend.http.request.methods.set-headers:
-**setServer**
- ``setServer(Zend\Stdlib\ParametersInterface $server)``
+**setHeaders**
+ ``setHeaders(Zend\Http\Headers $headers)``
- Provide an alternate Parameter Container implementation for server parameters in this object. (This is NOT the
- primary API for value setting; for that, see ``server()``.)
+ Provide an alternate Parameter Container implementation for headers in this object, (this is NOT the primary API
+ for value setting, for that see ``getHeaders()``).
Returns ``Zend\Http\Request``
-.. _zend.http.request.methods.server:
-
-**server**
- ``server()``
+.. _zend.http.request.methods.get-headers:
- Return the parameter container responsible for server parameters
+**getHeaders**
+ ``getHeaders(string|null $name, mixed|null $default)``
- Returns ``Zend\Stdlib\ParametersInterface``
+ Return the container responsible for storing HTTP headers. This container exposes the primary API for
+ manipulating headers set in the HTTP request. See :ref:`the section on Zend\\Http\\Headers<zend.http.headers>`
+ for more information.
-.. _zend.http.request.methods.set-env:
+ Returns ``Zend\Http\Headers`` if ``$name`` is ``null``.
+ Returns ``Zend\Http\Header\HeaderInterface`` or ``ArrayIterator`` if ``$name`` matches one or more stored headers, respectively.
-**setEnv**
- ``setEnv(Zend\Stdlib\ParametersInterface $env)``
-
- Provide an alternate Parameter Container implementation for env parameters in this object. (This is NOT the
- primary API for value setting; for that, see ``env()``.)
-
- Returns ``Zend\Http\Request``
-
-.. _zend.http.request.methods.env:
-
-**env**
- ``env()``
-
- Return the parameter container responsible for env parameters
-
- Returns ``Zend\Stdlib\ParametersInterface``
+.. _zend.stdlib.message.methods.set-metadata:
-.. _zend.http.request.methods.set-header:
+**setMetadata**
+ ``setMetadata(string|int|array|Traversable $spec, mixed $value)``
-**setHeader**
- ``setHeader(Zend\Http\Headers $headers)``
+ Set message metadata.
- Provide an alternate Parameter Container implementation for headers in this object. (This is NOT the primary API
- for value setting; for that, see ``header()``.)
+ Non-destructive setting of message metadata; always adds to the metadata, never overwrites the entire metadata
+ container.
Returns ``Zend\Http\Request``
-.. _zend.http.request.methods.header:
+.. _zend.stdlib.message.methods.get-metadata:
-**header**
- ``header()``
+**getMetadata**
+ ``getMetadata(null|string|int $key, null|mixed $default)``
- Return the header container responsible for headers
+ Retrieve all metadata or a single metadatum as specified by key.
- Returns ``Zend\Http\Headers``
+ Returns mixed
-.. _zend.http.request.methods.set-raw-body:
+.. _zend.stdlib.message.methods.set-content:
-**setRawBody**
- ``setRawBody(string $string)``
+**setContent**
+ ``setContent(mixed $value)``
- Set the raw body for the request
+ Set request body (content).
Returns ``Zend\Http\Request``
-.. _zend.http.request.methods.get-raw-body:
+.. _zend.stdlib.message.methods.get-content:
-**getRawBody**
- ``getRawBody()``
+**getContent**
+ ``getContent()``
- Get the raw body for the request
+ Get request body (content).
- Returns string
+ Returns mixed
.. _zend.http.request.methods.is-options:
@@ -359,69 +348,57 @@ Available Methods
Returns bool
-.. _zend.http.request.methods.render-request-line:
-
-**renderRequestLine**