/en/core-utility-libraries/httpsocket.rst
ReStructuredText | 382 lines | 275 code | 107 blank | 0 comment | 0 complexity | d02fe7c109a9d8d4ffe79bb4cc22500a MD5 | raw file
- HttpSocket
- ##########
- .. php:class:: HttpSocket(mixed $config = array())
- CakePHP includes an HttpSocket class which can be used easily for
- making requests. It is a great way to communicate with external webservices, or
- remote apis.
- Making a request
- ================
- You can use HttpSocket to create most kinds of HTTP requests with the different
- HTTP methods.
- .. php:method:: get($uri, $query, $request)
- The ``$query`` parameter, can either be a query string, or an array of keys
- and values. The get method makes a simple HTTP GET request returning the
- results::
- App::uses('HttpSocket', 'Network/Http');
- $HttpSocket = new HttpSocket();
- // string query
- $results = $HttpSocket->get('http://www.google.com/search', 'q=cakephp');
- // array query
- $results = $HttpSocket->get('http://www.google.com/search', array('q' => 'cakephp'));
- .. php:method:: post($uri, $data, $request)
- The post method makes a simple HTTP POST request returning the
- results.
- The parameters for the ``post`` method are almost the same as the
- get method, ``$uri`` is the web address where the request is being
- made; ``$query`` is the data to be posted, either as a string, or as
- an array of keys and values::
- App::uses('HttpSocket', 'Network/Http');
- $HttpSocket = new HttpSocket();
- // string data
- $results = $HttpSocket->post(
- 'http://example.com/add',
- 'name=test&type=user'
- );
- // array data
- $data = array('name' => 'test', 'type' => 'user');
- $results = $HttpSocket->post('http://example.com/add', $data);
- .. php:method:: put($uri, $data, $request)
- The put method makes a simple HTTP PUT request returning the
- results.
- The parameters for the ``put`` method is the same as the
- :php:meth:`~HttpSocket::post()` method.
- .. php:method:: delete($uri, $query, $request)
- The delete method makes a simple HTTP DELETE request returning the
- results.
- The parameters for the ``delete`` method is the same as the
- :php:meth:`~HttpSocket::get()` method. The ``$query`` parameter can either be a string or an array
- of query string arguments for the request.
- .. php:method:: patch($uri, $data, $request)
- The patch method makes a simple HTTP PATCH request returning the
- results.
- The parameters for the ``patch`` method is the same as the
- :php:meth:`~HttpSocket::post()` method.
- .. versionadded:: 2.4
- .. php:method:: request($request)
- The base request method, which is called from all the wrappers
- (get, post, put, delete). Returns the results of the request.
- $request is a keyed array of various options. Here is the format
- and default settings::
- public $request = array(
- 'method' => 'GET',
- 'uri' => array(
- 'scheme' => 'http',
- 'host' => null,
- 'port' => 80,
- 'user' => null,
- 'pass' => null,
- 'path' => null,
- 'query' => null,
- 'fragment' => null
- ),
- 'auth' => array(
- 'method' => 'Basic',
- 'user' => null,
- 'pass' => null
- ),
- 'version' => '1.1',
- 'body' => '',
- 'line' => null,
- 'header' => array(
- 'Connection' => 'close',
- 'User-Agent' => 'CakePHP'
- ),
- 'raw' => null,
- 'redirect' => false,
- 'cookies' => array()
- );
- Handling the response
- =====================
- Responses from requests made with ``HttpSocket`` are instances of
- ``HttpResponse``. This object gives you a few accessor methods to access the
- contents of an HTTP response. This class implements the
- `ArrayAccess <http://php.net/manual/en/class.arrayaccess.php>`_ and
- `__toString() <http://www.php.net/manual/en/language.oop5.magic.php#language.oop5.magic.tostring>`_,
- so you can continue using the ``$http->response`` as array and the return of
- request methods as string::
- App::uses('HttpSocket', 'Network/Http');
- $http = new HttpSocket();
- $response = $http->get('http://www.cakephp.org');
- // Check the body for the presence of a title tag.
- $titlePos = strpos($response->body, '<title>');
- // Get the status code for the response.
- $code = $response->code;
- The ``HttpResponse`` has the following attributes:
- * ``body`` returns body of HTTP response (normally the HTML).
- * ``headers`` returns array with headers.
- * ``cookies`` returns array with new cookies (cookies from others request are not stored here).
- * ``httpVersion`` returns string with HTTP version (from first line in response).
- * ``code`` returns the integer with HTTP code.
- * ``reasonPhrase`` returns the string with HTTP code response.
- * ``raw`` returns the unchanged response from server.
- The ``HttpResponse`` also exposes the following methods:
- * ``body()`` returns the body
- * ``isOk()`` returns if code is 200;
- * ``isRedirect()`` returns if code is 301, 302, 303 or 307 and the *Location* header is set.
- * ``getHeader()`` allows you to fetch headers, see the next section.
- Getting headers from a response
- -------------------------------
- Following others places in core, the HttpSocket does not change the casing of
- headers. :rfc:`2616` states that headers are case insensitive, and HttpSocket
- preserves the values the remote host sends::
- HTTP/1.1 200 OK
- Date: Mon, 16 Apr 2007 04:14:16 GMT
- server: CakeHttp Server
- content-tyPe: text/html
- Your ``$response->headers`` (or ``$response['header']``) will contain the exact
- keys sent. In order to safely access the header fields, it's best to use
- ``getHeader()``. If your headers looks like::
- Date: Mon, 16 Apr 2007 04:14:16 GMT
- server: CakeHttp Server
- content-tyPe: text/html
- You could fetch the above headers by calling::
- // $response is an instance of HttpResponse
- // get the Content-Type header.
- $response->getHeader('Content-Type');
- // get the date
- $response->getHeader('date');
- Headers can be fetched case-insensitively.
- Automatically handling a redirect response
- ------------------------------------------
- When the response has a valid redirect status code (see ``HttpResponse::isRedirect``),
- an extra request can be automatically done according to the received *Location* header::
- <?php
- App::uses('HttpSocket', 'Network/Http');
- $HttpSocket = new HttpSocket();
- $response = $HttpSocket->get('http://example.com/redirecting_url', array(), array('redirect' => true));
- The *redirect* option can take the following values
- * **true** : all redirecting responses will fire a consequent new request
- * **integer** : the set value is the maximum number of redirections allowed (after reaching it, the *redirect* value is considered as **false**)
- * **false** (default) : no consequent request will be fired
- The returned ``$response`` will be the final one, according to the settings.
- .. _http-socket-ssl-options:
- Handling SSL certificates
- -------------------------
- When making requests to SSL services HttpSocket will attempt to validate the SSL
- certifcate using peer validation. If the certificate fails peer validation or
- does not match the hostname being accessed the connection will fail, and an
- exception will be thrown. By default HttpSocket will use the mozilla certificate
- authority file to verify SSL certificates. You can use the following options to
- configure how SSL certificates are handled:
- - ``ssl_verify_peer`` Set to false to disable SSL verification. This is
- **not recommended**.
- - ``ssl_verify_host`` Set to false if you wish to ignore hostname match errors
- when validating certificates.
- - ``ssl_allow_self_signed`` Set to true to enable self-signed certificates to be
- accepted. This requires ``ssl_verify_peer`` to be enabled.
- - ``ssl_cafile`` Set to the absolute path of the Certificate Authority file that
- you wish to use for verifying SSL certificates.
- These options are provided as constructor arguments::
- $socket = new HttpSocket(array(
- 'ssl_allow_self_signed' => true
- ));
- Would allow self-signed certificates for all requests made with the created
- socket.
- .. versionadded:: 2.3
- SSL certificate validation was added in 2.3.
- Creating a custom response class
- --------------------------------
- You can create your own response class to use with HttpSocket. You could create
- the file ``app/Lib/Network/Http/YourResponse.php`` with the content::
- App::uses('HttpResponse', 'Network/Http');
- class YourResponse extends HttpResponse {
- public function parseResponse($message) {
- parent::parseResponse($message);
- // Make what you want
- }
- }
- Before your request you'll need to change the responseClass property::
- App::uses('HttpSocket', 'Network/Http');
- $http = new HttpSocket();
- $http->responseClass = 'YourResponse';
- .. versionchanged:: 2.3
- As of 2.3.0 you should extend ``HttpSocketResponse`` instead. This
- avoids a common issue with the HTTP PECL extension.
- Downloading the results
- -----------------------
- HttpSocket has a new method called `setContentResource()`. By setting a resource
- with this method, the content will be written to this resource, using
- `fwrite()`. To you download a file, you can do::
- App::uses('HttpSocket', 'Network/Http');
- $http = new HttpSocket();
- $f = fopen(TMP . 'bakery.xml', 'w');
- $http->setContentResource($f);
- $http->get('http://bakery.cakephp.org/comments.rss');
- fclose($f);
- .. note::
- The headers are not included in file, you will only get the body content
- written to your resource. To disable saving into the resource, use
- ``$http->setContentResource(false)``.
- Using authentication
- ====================
- HttpSocket supports a HTTP Basic and Digest authentication methods out of the
- box. You can also create custom authentication objects to support protocols
- like OAuth. To use any authentication system you need to configure the
- ``HttpSocket`` instance::
- App::uses('HttpSocket', 'Network/Http');
- $http = new HttpSocket();
- $http->configAuth('Basic', 'user', 'password');
- The above would configure the ``HttpSocket`` instance to use Basic
- authentication using ``user`` and ``password`` as the credentials.
- Creating a custom authentication object
- ---------------------------------------
- You can now create your own authentication method to use with HttpSocket. You
- could create the file ``app/Lib/Network/Http/YourMethodAuthentication.php`` with the
- content::
- class YourMethodAuthentication {
- /**
- * Authentication
- *
- * @param HttpSocket $http
- * @param array $authInfo
- * @return void
- */
- public static function authentication(HttpSocket $http, &$authInfo) {
- // Do something, for example set $http->request['header']['Authentication'] value
- }
- }
- To configure HttpSocket to use your auth configuration, you can use the new
- method ``configAuth()``::
- $http->configAuth('YourMethod', array('config1' => 'value1', 'config2' => 'value2'));
- $http->get('http://secure.your-site.com');
- The ``authentication()`` method will be called to append the request headers.
- Using a HttpSocket with a proxy
- -------------------------------
- As part of auth configuration, you can configure proxy authentication. You can
- create your customized method to proxy authentication in the same class of
- authentication. For example::
- class YourMethodAuthentication {
- /**
- * Authentication
- *
- * @param HttpSocket $http
- * @param array $authInfo
- * @return void
- */
- public static function authentication(HttpSocket $http, &$authInfo) {
- // Do something, for example set $http->request['header']['Authentication'] value
- }
- /**
- * Proxy Authentication
- *
- * @param HttpSocket $http
- * @param array $proxyInfo
- * @return void
- */
- public static function proxyAuthentication(HttpSocket $http, &$proxyInfo) {
- // Do something, for example set $http->request['header']['Proxy-Authentication'] value
- }
- }
- .. note::
- To use a proxy, you must call the ``HttpSocket::configProxy()`` similar to
- ``HttpSocket::configAuth()``.
- .. meta::
- :title lang=en: HttpSocket
- :keywords lang=en: array name,array data,query parameter,query string,php class,string query,test type,string data,google,query results,webservices,apis,parameters,cakephp,meth,search results