diff options
author | diosmosis <benakamoorthi@fastmail.fm> | 2013-10-20 06:17:09 +0400 |
---|---|---|
committer | diosmosis <benakamoorthi@fastmail.fm> | 2013-10-21 07:25:59 +0400 |
commit | 31fe03420a06fa9d47a0d51ddb664b68e679d4cf (patch) | |
tree | d1fd6fdce913559f3a16e3b291439df77b18e525 /core/Http.php | |
parent | 21b1c006efcaf6c8b2f86427968ab1056ee5c925 (diff) |
Refs #4200, documented Http class.
Diffstat (limited to 'core/Http.php')
-rw-r--r-- | core/Http.php | 118 |
1 files changed, 84 insertions, 34 deletions
diff --git a/core/Http.php b/core/Http.php index 65be4de797..13cb5fc6a6 100644 --- a/core/Http.php +++ b/core/Http.php @@ -17,14 +17,14 @@ use Exception; * Used to check for the latest Piwik version and download updates. * * @package Piwik - * @api */ class Http { /** - * Get "best" available transport method for sendHttpRequest() calls. - * - * @return string + * Returns the "best" available transport method for [sendHttpRequest()](#sendHttpRequest) calls. + * + * @return string Either `'curl'`, `'fopen'` or `'socket'`. + * @api */ public static function getTransportMethod() { @@ -52,23 +52,30 @@ class Http } /** - * Sends http request ensuring the request will fail before $timeout seconds - * If no $destinationPath is specified, the trimmed response (without header) is returned as a string. - * If a $destinationPath is specified, the response (without header) is saved to a file. - * - * @param string $aUrl - * @param int $timeout - * @param string $userAgent - * @param string $destinationPath - * @param int $followDepth - * @param bool $acceptLanguage - * @param array|bool $byteRange For Range: header. Should be two element array of bytes, eg, array(0, 1024) - * Doesn't work w/ fopen method. - * @param bool $getExtendedInfo True to return status code, headers & response, false if just response. - * @param string $httpMethod The HTTP method to use. Defaults to 'GET'. + * Sends an HTTP request using best available transport method. * - * @throws Exception - * @return bool true (or string) on success; false on HTTP response error code (1xx or 4xx) + * @param string $aUrl The target URL. + * @param int $timeout The number of seconds to wait before aborting the HTTP request. + * @param string|null $userAgent The user agent to use. + * @param string|null $destinationPath If supplied, the HTTP response will be saved to the file specified by + * this path. + * @param int|null $followDepth Internal redirect count. Should always pass `null` for this parameter. + * @param bool $acceptLanguage The value to use for the `'Accept-Language'` HTTP request header. + * @param array|bool $byteRange For `Range:` header. Should be two element array of bytes, eg, `array(0, 1024)` + * Doesn't work w/ `fopen` transport method. + * @param bool $getExtendedInfo If true returns the status code, headers & response, if false just the response. + * @param string $httpMethod The HTTP method to use. Defaults to `'GET'`. + * @throws Exception if the response cannot be saved to `$destinationPath`, if the HTTP response cannot be sent, + * if there are more than 5 redirects or if the request times out. + * @return bool|string If `$destinationPath` is not specified the HTTP response is returned on success. `false` + * is returned on failure. + * If `$getExtendedInfo` is `true` and `$destinationPath` is not specified an array with + * the following information is returned on success: + * - status => the HTTP status code + * - headers => the HTTP headers + * - data => the HTTP response data + * `false` is still returned on failure. + * @api */ public static function sendHttpRequest($aUrl, $timeout, $userAgent = null, $destinationPath = null, $followDepth = 0, $acceptLanguage = false, $byteRange = false, $getExtendedInfo = false, $httpMethod = 'GET') { @@ -101,7 +108,7 @@ class Http * @param array|bool $byteRange For Range: header. Should be two element array of bytes, eg, array(0, 1024) * Doesn't work w/ fopen method. * @param bool $getExtendedInfo True to return status code, headers & response, false if just response. - * @param string $httpMethod The HTTP method to use. Defaults to 'GET'. + * @param string $httpMethod The HTTP method to use. Defaults to `'GET'`. * * @throws Exception * @return bool true (or string/array) on success; false on HTTP response error code (1xx or 4xx) @@ -533,17 +540,58 @@ class Http /** * Downloads the next chunk of a specific file. The next chunk's byte range * is determined by the existing file's size and the expected file size, which - * is stored in the piwik_option table before starting a download. - * Note this function uses the Range HTTP header to accomplish downloading in + * is stored in the piwik_option table before starting a download. The expected + * file size is obtained through a `HEAD` HTTP request. + * + * Note: this function uses the `Range` HTTP header to accomplish downloading in * parts. + * + * The proper use of this function is to call it once per request. The browser + * should continue to send requests to Piwik which will in turn call this method + * until the file has completely downloaded. In this way, the user can be informed + * of a download's progress. + * + * **Example Usage** + * + * ``` + * // browser JavaScript + * var downloadFile = function (isStart) { + * var ajax = new ajaxHelper(); + * ajax.addParams({ + * module: 'MyPlugin', + * action: 'myAction', + * isStart: isStart ? 1 : 0 + * }, 'post'); + * ajax.setCallback(function (response) { + * var progress = response.progress + * // ...update progress... * + * downloadFile(false); + * }); + * ajax.send(); + * } + * + * downloadFile(true); + * ``` + * + * ``` + * // PHP controller action + * public function myAction() + * { + * $outputPath = PIWIK_INCLUDE_PATH . '/tmp/averybigfile.zip'; + * $isStart = Common::getRequestVar('isStart', 1, 'int'); + * Http::downloadChunk("http://bigfiles.com/averybigfile.zip", $outputPath, $isStart == 1); + * } + * ``` + * * @param string $url The url to download from. * @param string $outputPath The path to the file to save/append to. * @param bool $isContinuation True if this is the continuation of a download, - * or if we're starting a fresh one. - * - * @throws Exception + * or if we're starting a fresh one. + * @throws Exception if the file already exists and we're starting a new download, + * if we're trying to continue a download that never started * @return array + * @api */ public static function downloadChunk($url, $outputPath, $isContinuation) { @@ -652,20 +700,22 @@ class Http } /** - * Fetch the file at $url in the destination $destinationPath + * Fetches a file located at `$url` and saves it to `$destinationPath`. * - * @param string $url - * @param string $destinationPath - * @param int $tries - * @param int $timeout - * @throws Exception - * @return bool true on success, throws Exception on failure + * @param string $url The URL of the file to download. + * @param string $destinationPath The path to download the file to. + * @param int $tries (deprecated) + * @param int $timeout The amount of seconds to wait before aborting the HTTP request. + * @throws Exception if the response cannot be saved to `$destinationPath`, if the HTTP response cannot be sent, + * if there are more than 5 redirects or if the request times out. + * @return bool true on success, throws Exception on failure + * @api */ public static function fetchRemoteFile($url, $destinationPath = null, $tries = 0, $timeout = 10) { @ignore_user_abort(true); SettingsServer::setMaxExecutionTime(0); - return self::sendHttpRequest($url, $timeout, 'Update', $destinationPath, $tries); + return self::sendHttpRequest($url, $timeout, 'Update', $destinationPath); } /** |