From e3bc28a330416ca3e82d19a41cb3368b5d69e68a Mon Sep 17 00:00:00 2001 From: mark_story Date: Sat, 29 Dec 2012 20:53:43 -0500 Subject: [PATCH] Add more documentation. --- lib/Cake/Network/Http/Adapter/Stream.php | 9 ++++-- lib/Cake/Network/Http/Client.php | 40 ++++++++++++++++++++++++ lib/Cake/Network/Http/Message.php | 4 +++ lib/Cake/Network/Http/Request.php | 17 +++++++++- lib/Cake/Network/Http/Response.php | 22 ++++++++----- 5 files changed, 81 insertions(+), 11 deletions(-) diff --git a/lib/Cake/Network/Http/Adapter/Stream.php b/lib/Cake/Network/Http/Adapter/Stream.php index 4d9ca2f4697..04cae051e77 100644 --- a/lib/Cake/Network/Http/Adapter/Stream.php +++ b/lib/Cake/Network/Http/Adapter/Stream.php @@ -202,10 +202,11 @@ protected function _buildSslContext(Request $request, $options) { /** * Open the stream and send the request. * - * @return void + * @param Request $request + * @return Response The populated response object. * @throws Cake\Error\Exception */ - protected function _send($request) { + protected function _send(Request $request) { $url = $request->url(); $this->_open($url); $content = ''; @@ -255,7 +256,9 @@ protected function _connectionErrorHandler($code, $message) { } /** - * Get the contextOptions. + * Get the context options + * + * Useful for debugging and testing context creation. * * @return array */ diff --git a/lib/Cake/Network/Http/Client.php b/lib/Cake/Network/Http/Client.php index b115f96c843..9a0e3400711 100644 --- a/lib/Cake/Network/Http/Client.php +++ b/lib/Cake/Network/Http/Client.php @@ -25,8 +25,21 @@ * * ### Scoped clients * + * If you're doing multiple requests to the same hostname its often convienent + * to use the constructor arguments to create a scoped client. This allows you + * to keep your code DRY and not repeat hostnames, authentication, and other options. + * * ### Doing requests * + * Once you've created an instance of Client you can do requests + * using several methods. Each corresponds to a different HTTP method. + * + * - get() + * - post() + * - put() + * - delete() + * - patch() + * * ### Sending request bodies * * By default any POST/PUT/PATCH/DELETE request with $data will @@ -44,9 +57,23 @@ * * ### Using authentication * + * By using the `auth` key you can use authentication. The type sub option + * can be used to specify which authentication strategy you want to use. + * CakePHP comes with a few built-in strategies: + * + * - Basic + * - Digest + * - Oauth * * ### Using proxies * + * By using the `proxy` key you can set authentication credentials for + * a proxy if you need to use one.. The type sub option can be used to + * specify which authentication strategy you want to use. + * CakePHP comes with a few built-in strategies: + * + * - Basic + * - Digest * */ class Client { @@ -80,6 +107,19 @@ class Client { * * ### Config options * + * You can set the following options when creating a client: + * + * - host - The hostname to do requests on. + * - port - The port to use. + * - scheme - The default scheme/protocol to use. Defaults to http. + * - timeout - The timeout in seconds. Defaults to 30 + * - ssl_verify_peer - Whether or not SSL certificates should be validated. + * Defaults to true. + * - ssl_verify_depth - The maximum certificate chain depth to travers. + * Defaults to 5. + * - ssl_verify_host - Verify that the certificate and hostname match. + * Defaults to true. + * - redirect - Number of redirects to follow. Defaults to false. * * @param array $config Config options for scoped clients. */ diff --git a/lib/Cake/Network/Http/Message.php b/lib/Cake/Network/Http/Message.php index da872fab0eb..58d384d36ac 100644 --- a/lib/Cake/Network/Http/Message.php +++ b/lib/Cake/Network/Http/Message.php @@ -24,6 +24,10 @@ class Message { const STATUS_OK = 200; const STATUS_CREATED = 201; const STATUS_ACCEPTED = 202; + const STATUS_MOVED_PERMANENTLY = 301; + const STATUS_FOUND = 302; + const STATUS_SEE_OTHER = 303; + const STATUS_TEMPORARY_REDIRECT = 307; const METHOD_GET = 'GET'; const METHOD_POST = 'POST'; diff --git a/lib/Cake/Network/Http/Request.php b/lib/Cake/Network/Http/Request.php index bc8e0d28b91..aac92069333 100644 --- a/lib/Cake/Network/Http/Request.php +++ b/lib/Cake/Network/Http/Request.php @@ -24,10 +24,25 @@ */ class Request extends Message { - protected $_method; +/** + * The HTTP method to use. + * + * @var string + */ + protected $_method = self::METHOD_GET; +/** + * Request body to send. + * + * @var mixed + */ protected $_body; +/** + * The URL to request. + * + * @var string + */ protected $_url; /** diff --git a/lib/Cake/Network/Http/Response.php b/lib/Cake/Network/Http/Response.php index 4353d7144fb..ea30290c912 100644 --- a/lib/Cake/Network/Http/Response.php +++ b/lib/Cake/Network/Http/Response.php @@ -173,10 +173,12 @@ protected function _parseCookie($value) { * @return boolean */ public function isOk() { - return in_array( - $this->_code, - [static::STATUS_OK, static::STATUS_CREATED, static::STATUS_ACCEPTED] - ); + $codes = [ + static::STATUS_OK, + static::STATUS_CREATED, + static::STATUS_ACCEPTED + ]; + return in_array($this->_code, $codes); } /** @@ -185,8 +187,14 @@ public function isOk() { * @return boolean */ public function isRedirect() { + $codes = [ + static::STATUS_MOVED_PERMANENTLY, + static::STATUS_FOUND, + static::STATUS_SEE_OTHER, + static::STATUS_TEMPORARY_REDIRECT, + ]; return ( - in_array($this->_code, array(301, 302, 303, 307)) && + in_array($this->_code, $codes) && $this->header('Location') ); } @@ -317,7 +325,7 @@ public function offsetExists($name) { * @return null */ public function offsetSet($name, $value) { - + } /** @@ -327,7 +335,7 @@ public function offsetSet($name, $value) { * @return null */ public function offsetUnset($name) { - + } }