Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Updating doc blocks for HttpSocket and File.

  • Loading branch information...
commit 7459da2affccf9d48052ef41ffc808d8e07f33b1 1 parent b33fdba
@markstory markstory authored
Showing with 115 additions and 49 deletions.
  1. +12 −10 cake/libs/file.php
  2. +103 −39 cake/libs/http_socket.php
View
22 cake/libs/file.php
@@ -171,7 +171,7 @@ function open($mode = 'r', $force = false) {
* Return the contents of this File as a string.
*
* @param string $bytes where to start
- * @param string $mode
+ * @param string $mode A `fread` compatible mode.
* @param boolean $force If true then the file will be re-opened even if its already opened, otherwise it won't
* @return mixed string on success, false on failure
* @access public
@@ -225,11 +225,12 @@ function offset($offset = false, $seek = SEEK_SET) {
}
/**
- * Prepares a ascii string for writing
- * fixes line endings
+ * Prepares a ascii string for writing. Converts line endings to the
+ * correct terminator for the current platform. If windows "\r\n" will be used
+ * all other platforms will use "\n"
*
* @param string $data Data to prepare for writing.
- * @return string
+ * @return string The with converted line endings.
* @access public
*/
function prepare($data, $forceWindows = false) {
@@ -243,9 +244,9 @@ function prepare($data, $forceWindows = false) {
/**
* Write given data to this File.
*
- * @param string $data Data to write to this File.
- * @param string $mode Mode of writing. {@link http://php.net/fwrite See fwrite()}.
- * @param string $force force the file to open
+ * @param string $data Data to write to this File.
+ * @param string $mode Mode of writing. {@link http://php.net/fwrite See fwrite()}.
+ * @param string $force force the file to open
* @return boolean Success
* @access public
*/
@@ -272,7 +273,7 @@ function write($data, $mode = 'w', $force = false) {
* Append given data string to this File.
*
* @param string $data Data to write
- * @param string $force force the file to open
+ * @param string $force force the file to open
* @return boolean Success
* @access public
*/
@@ -360,7 +361,8 @@ function name() {
/**
* makes filename safe for saving
*
- * @param string $name the name of the file to make safe if different from $this->name
+ * @param string $name The name of the file to make safe if different from $this->name
+ * @param strin $ext The name of the extension to make safe if different from $this->ext
* @return string $ext the extension of the file
* @access public
*/
@@ -487,7 +489,7 @@ function owner() {
}
/**
- * Returns the File group.
+ * Returns the File's group.
*
* @return integer the Filegroup
* @access public
View
142 cake/libs/http_socket.php
@@ -22,7 +22,8 @@
/**
* Cake network socket connection class.
*
- * Core base class for HTTP network communication.
+ * Core base class for HTTP network communication. HttpSocket can be used as an
+ * Object Oriented replacement for cURL in many places.
*
* @package cake
* @subpackage cake.cake.libs
@@ -112,10 +113,10 @@ class HttpSocket extends CakeSocket {
*/
var $config = array(
'persistent' => false,
- 'host' => 'localhost',
- 'protocol' => 'tcp',
- 'port' => 80,
- 'timeout' => 30,
+ 'host' => 'localhost',
+ 'protocol' => 'tcp',
+ 'port' => 80,
+ 'timeout' => 30,
'request' => array(
'uri' => array(
'scheme' => 'http',
@@ -142,7 +143,24 @@ class HttpSocket extends CakeSocket {
/**
* Build an HTTP Socket using the specified configuration.
*
- * @param array $config Configuration
+ * You can use a url string to set the url and use default configurations for
+ * all other options:
+ *
+ * `$http =& new HttpSockect('http://cakephp.org/');`
+ *
+ * Or use an array to configure multiple options:
+ *
+ * {{{
+ * $http =& new HttpSocket(array(
+ * 'host' => 'cakephp.org',
+ * 'timeout' => 20
+ * ));
+ * }}}
+ *
+ * See HttpSocket::$config for options that can be used.
+ *
+ * @param mixed $config Configuration information, either a string url or an array of options.
+ * @access public
*/
function __construct($config = array()) {
if (is_string($config)) {
@@ -158,7 +176,8 @@ function __construct($config = array()) {
}
/**
- * Issue the specified request.
+ * Issue the specified request. HttpSocket::get() and HttpSocket::post() wrap this
+ * method and provide a more granular interface.
*
* @param mixed $request Either an URI string, or an array defining host/uri
* @return mixed false on error, request body on success
@@ -270,15 +289,30 @@ function request($request = array()) {
/**
* Issues a GET request to the specified URI, query, and request.
*
- * @param mixed $uri URI to request (see {@link _parseUri()})
- * @param array $query Query to append to URI
+ * Using a string uri and an array of query string parameters:
+ *
+ * `$response = $http->get('http://google.com/search', array('q' => 'cakephp', 'client' => 'safari'));`
+ *
+ * Would do a GET request to `http://google.com/search?q=cakephp&client=safari`
+ *
+ * You could express the same thing using a uri array and query string parameters:
+ *
+ * {{{
+ * $response = $http->get(
+ * array('host' => 'google.com', 'path' => '/search'),
+ * array('q' => 'cakephp', 'client' => 'safari')
+ * );
+ * }}}
+ *
+ * @param mixed $uri URI to request. Either a string uri, or a uri array, see HttpSocket::_parseUri()
+ * @param array $query Querystring parameters to append to URI
* @param array $request An indexed array with indexes such as 'method' or uri
- * @return mixed Result of request
+ * @return mixed Result of request, either false on failure or the response to the request.
* @access public
*/
function get($uri = null, $query = array(), $request = array()) {
if (!empty($query)) {
- $uri =$this->_parseUri($uri);
+ $uri = $this->_parseUri($uri);
if (isset($uri['query'])) {
$uri['query'] = array_merge($uri['query'], $query);
} else {
@@ -294,10 +328,19 @@ function get($uri = null, $query = array(), $request = array()) {
/**
* Issues a POST request to the specified URI, query, and request.
*
- * @param mixed $uri URI to request (see {@link _parseUri()})
- * @param array $query Query to append to URI
+ * `post()` can be used to post simple data arrays to a url:
+ *
+ * {{{
+ * $response = $http->post('http://example.com', array(
+ * 'username' => 'batman',
+ * 'password' => 'bruce_w4yne'
+ * ));
+ * }}}
+ *
+ * @param mixed $uri URI to request. See HttpSocket::_parseUri()
+ * @param array $data Array of POST data keys and values.
* @param array $request An indexed array with indexes such as 'method' or uri
- * @return mixed Result of request
+ * @return mixed Result of request, either false on failure or the response to the request.
* @access public
*/
function post($uri = null, $data = array(), $request = array()) {
@@ -308,8 +351,8 @@ function post($uri = null, $data = array(), $request = array()) {
/**
* Issues a PUT request to the specified URI, query, and request.
*
- * @param mixed $uri URI to request (see {@link _parseUri()})
- * @param array $query Query to append to URI
+ * @param mixed $uri URI to request, See HttpSocket::_parseUri()
+ * @param array $data Array of PUT data keys and values.
* @param array $request An indexed array with indexes such as 'method' or uri
* @return mixed Result of request
* @access public
@@ -323,7 +366,7 @@ function put($uri = null, $data = array(), $request = array()) {
* Issues a DELETE request to the specified URI, query, and request.
*
* @param mixed $uri URI to request (see {@link _parseUri()})
- * @param array $query Query to append to URI
+ * @param array $data Query to append to URI
* @param array $request An indexed array with indexes such as 'method' or uri
* @return mixed Result of request
* @access public
@@ -334,11 +377,31 @@ function delete($uri = null, $data = array(), $request = array()) {
}
/**
- * undocumented function
+ * Normalizes urls into a $uriTemplate. If no template is provided
+ * a default one will be used. Will generate the url using the
+ * current config information.
+ *
+ * ### Usage:
+ *
+ * After configuring part of the request parameters, you can use url() to generate
+ * urls.
+ *
+ * {{{
+ * $http->configUri('http://www.cakephp.org');
+ * $url = $http->url('/search?q=bar');
+ * }}}
+ *
+ * Would return `http://www.cakephp.org/search?q=bar`
+ *
+ * url() can also be used with custom templates:
+ *
+ * `$url = $http->url('http://www.cakephp/search?q=socket', '/%path?%query');`
+ *
+ * Would return `/search?q=socket`.
*
- * @param unknown $url
- * @param unknown $uriTemplate
- * @return void
+ * @param mixed $url Either a string or array of url options to create a url with.
+ * @param string $uriTemplate A template string to use for url formatting.
+ * @return mixed Either false on failure or a string containing the composed url.
* @access public
*/
function url($url = null, $uriTemplate = null) {
@@ -435,9 +498,9 @@ function _parseResponse($message) {
* Generic function to decode a $body with a given $encoding. Returns either an array with the keys
* 'body' and 'header' or false on failure.
*
- * @param string $body A string continaing the body to decode
- * @param mixed $encoding Can be false in case no encoding is being used, or a string representing the encoding
- * @return mixed Array or false
+ * @param string $body A string continaing the body to decode.
+ * @param mixed $encoding Can be false in case no encoding is being used, or a string representing the encoding.
+ * @return mixed Array of response headers and body or false.
* @access protected
*/
function _decodeBody($body, $encoding = 'chunked') {
@@ -462,8 +525,8 @@ function _decodeBody($body, $encoding = 'chunked') {
* Decodes a chunked message $body and returns either an array with the keys 'body' and 'header' or false as
* a result.
*
- * @param string $body A string continaing the chunked body to decode
- * @return mixed Array or false
+ * @param string $body A string continaing the chunked body to decode.
+ * @return mixed Array of response headers and body or false.
* @access protected
*/
function _decodeChunkedBody($body) {
@@ -524,7 +587,7 @@ function _decodeChunkedBody($body) {
/**
* Parses and sets the specified URI into current request configuration.
*
- * @param mixed $uri URI (see {@link _parseUri()})
+ * @param mixed $uri URI, See HttpSocket::_parseUri()
* @return array Current configuration settings
* @access protected
*/
@@ -557,9 +620,9 @@ function _configUri($uri = null) {
/**
* Takes a $uri array and turns it into a fully qualified URL string
*
- * @param array $uri A $uri array, or uses $this->config if left empty
- * @param string $uriTemplate The Uri template/format to use
- * @return string A fully qualified URL formated according to $uriTemplate
+ * @param mixed $uri Either A $uri array, or a request string. Will use $this->config if left empty.
+ * @param string $uriTemplate The Uri template/format to use.
+ * @return mixed A fully qualified URL formated according to $uriTemplate, or false on failure
* @access protected
*/
function _buildUri($uri = array(), $uriTemplate = '%scheme://%user:%pass@%host:%port/%path?%query#%fragment') {
@@ -668,11 +731,12 @@ function _parseUri($uri = null, $base = array()) {
* - ?key[subKey]=value
* - ?key[]=value1&key[]=value2
*
- * A leading '?' mark in $query is optional and does not effect the outcome of this function. For the complete capabilities of this implementation
- * take a look at HttpSocketTest::testparseQuery()
+ * A leading '?' mark in $query is optional and does not effect the outcome of this function.
+ * For the complete capabilities of this implementation take a look at HttpSocketTest::testparseQuery()
*
* @param mixed $query A query string to parse into an array or an array to return directly "as is"
- * @return array The $query parsed into a possibly multi-level array. If an empty $query is given, an empty array is returned.
+ * @return array The $query parsed into a possibly multi-level array. If an empty $query is
+ * given, an empty array is returned.
* @access protected
*/
function _parseQuery($query) {
@@ -857,10 +921,10 @@ function _parseHeader($header) {
}
/**
- * undocumented function
+ * Parses cookies in response headers.
*
- * @param unknown $header
- * @return void
+ * @param array $header Header array containing one ore more 'Set-Cookie' headers.
+ * @return mixed Either false on no cookies, or an array of cookies recieved.
* @access public
* @todo Make this 100% RFC 2965 confirm
*/
@@ -899,10 +963,10 @@ function parseCookies($header) {
}
/**
- * undocumented function
+ * Builds cookie headers for a request.
*
- * @param unknown $cookies
- * @return void
+ * @param array $cookies Array of cookies to send with the request.
+ * @return string Cookie header string to be sent with the request.
* @access public
* @todo Refactor token escape mechanism to be configurable
*/
Please sign in to comment.
Something went wrong with that request. Please try again.