You are here

Home » API reference » HTTP Parallel Request & Threading Library 7 » httprl.module

function httprl_request in HTTP Parallel Request & Threading Library 7

Same name and namespace in other branches
  1. 6 httprl.module \httprl_request()

Queue up a HTTP request in httprl_send_request.

This is a flexible and powerful HTTP client implementation. Correctly handles GET, POST, PUT or any other HTTP requests.

Parameters

string|array $urls: A string or an array containing a fully qualified URI(s).

array $options: (optional) An array that can have one or more of the following elements:

  • headers: An array containing request headers to send as name/value pairs. Some of the more useful headers:

    • For POST: 'Content-Type' => 'application/x-www-form-urlencoded',
    • Limit number of bytes server sends back: 'Range' => 'bytes=0-1024',
    • Compression: 'Accept-Encoding' => 'gzip, deflate',
    • Let server know where request came from: 'Referer' => 'example.com',
    • Content-Types that are acceptable: 'Accept' => 'text/plain',
    • Send Cookies: 'Cookie' => 'key1=value1; key2=value2;',
    • Skip the cache: 'Cache-Control' => 'no-cache',
    • Skip the cache: 'Pragma' => 'no-cache',

    List of headers: http://en.wikipedia.org/wiki/List_of_HTTP_header_fields

  • method: A string containing the request method. Defaults to 'GET'.
  • data: A string containing the request body, formatted as 'param=value&param=value&...'. Defaults to NULL.
  • max_redirects: An integer representing how many times a redirect may be followed. Defaults to 3.
  • timeout: A float representing the maximum number of seconds a connection may take. The default is 30 seconds. If a timeout occurs, the error code is set to the HTTPRL_REQUEST_ABORTED constant.
  • dns_timeout: A float representing the maximum number of seconds a DNS lookup request may take. The default is 5 seconds. If a timeout occurs, the error code is set to the HTTPRL_HOST_NOT_FOUND constant.
  • connect_timeout: A float representing the maximum number of seconds establishing the TCP connection may take. The default is 5 seconds. If a timeout occurs, the error code is set to the HTTPRL_REQUEST_TIMEOUT constant.
  • ttfb_timeout: A float representing the maximum number of seconds a connection may take to download the first byte. The default is 20 seconds. If a timeout occurs, the error code is set to the HTTPRL_REQUEST_ABORTED constant.
  • context: A context resource created with stream_context_create().
  • secure_socket_transport: The transport to use when making secure requests over HTTPS; see http://php.net/manual/en/transports.inet.php for more information. The value should be 'ssl', 'sslv2', 'sslv3' or 'tls'. Defaults to 'ssl', which will work for HTTPS requests to most remote servers.
  • blocking: set to FALSE to make this not care about the returned data.
  • version: HTTP Version 1.0 or 1.1. Default is 1.0 for a good reason.
  • referrer: TRUE - send current page; FALSE - do not send current page. Default is FALSE.
  • domain_connections: Maximum number of simultaneous connections to a given domain name. Default is 8.
  • global_connections: Maximum number of simultaneous connections that can be open on the server. Default is 128.
  • global_timeout: A float representing the maximum number of seconds the function call may take. If a timeout occurs,the error code is set to the HTTPRL_FUNCTION_TIMEOUT constant. Default is 120 seconds.
  • chunk_size_write: max size of what will be written in fwrite().
  • chunk_size_read: max size of what will be read from fread().
  • async_connect: default is TRUE. FALSE may give more info on errors but is generally slower.
  • callback: Array where the first value is an array of options; the result is passed to the callback function as the first argument, the other options passed in this array are passed in after the result. The options array needs to contain the function name and the target variable for the result of the function.
  • background_callback: Array where the first value is an array of options; the result is passed to the callback function as the first argument, the other options passed in this array are passed in after the result. The options array needs to contain the function name. If the return or printed keys are not defined this function will run in non blocking mode and the parent will not be able to get the result; if the return or printed keys defined then this function will run in blocking mode and the returned and printed data as well as any variables passed by reference will be available to the parent.
  • alter_all_streams_function: Function name. This function runs at the end of httprl_post_processing() so that one can alter the $responses and $output variables inside of httprl_send_request. Defined function should have the following parameters: ($id, &$responses).
  • stall_fread: TRUE or FALSE. If true once all fwrites have been done httprl_send_request() will return. You will need to call httprl_send_request() a second time to read the responses back.
  • ping_db: After X amount of time, ping the DB with a simple query in order to keep the connection alive. Default is every 20 seconds. Set to 0 to disable.
  • ignore_empty_chunk: an empty chunk returned from a stream will: default FALSE - make the connection not 'alive' and stop reading; TRUE - not stop a stream from being 'alive' and will continue to read until EOF or timeout.

Return value

array Array where key is the URL and the value is the return value from httprl_send_request.

See also

drupal_http_request()

4 calls to httprl_request()
httprl.examples.php in examples/httprl.examples.php
HTTP Parallel Request Library code examples.
httprl_override_core in ./httprl.module
Queue and send off http request.
httprl_parse_data in ./httprl.module
Extract the header and meta data from the http data stream.
httprl_queue_background_callback in ./httprl.module
Run callback in the background.

File

./httprl.module, line 1186
HTTP Parallel Request Library module.

Code

function httprl_request($urls, array $options = array()) {

  // See if a full bootstrap has been done.
  $full_bootstrap = httprl_drupal_full_bootstrap();

  // Transform string to an array.
  if (!is_array($urls)) {
    $temp =& $urls;
    unset($urls);
    $urls = array(
      &$temp,
    );
    unset($temp);
  }
  if ($full_bootstrap) {

    // Allow other modules to alter things before we get started.
    // Run hook_pre_httprl_request_alter().
    $data = array(
      $urls,
      $options,
    );
    drupal_alter('pre_httprl_request', $data);
    list($urls, $options) = $data;
  }
  $connections = array();
  $return = array();

  // Set things up; but do not perform any IO.
  foreach ($urls as &$url) {
    $result = new stdClass();
    $result->url =& $url;
    $result->status = 'Connecting.';
    $result->code = 0;
    $result->chunk_size = 1024;
    $result->data = '';

    // Copy Options.
    $these_options = $options;

    // Setup the default options.
    httprl_set_default_options($these_options);

    // Parse the given URL and skip if an error occurred.
    $uri = httprl_parse_url($url, $result);
    if (isset($result->error)) {

      // Put all variables into an array for easy alterations.
      $connections[] = array(
        NULL,
        NULL,
        $uri,
        $url,
        $these_options,
        $result,
        NULL,
      );
      $return[$url] = FALSE;

      // Stop processing this request as we have encountered an error.
      continue;
    }

    // Set the proxy server if one is required.
    $proxy_server = httprl_setup_proxy($uri, $these_options, $url);

    // Create the socket string and skip if an error occurred.
    $socket = httprl_set_socket($uri, $these_options, $proxy_server, $result, $return, $url);
    if (isset($result->error)) {

      // Put all variables into an array for easy alterations.
      $connections[] = array(
        $socket,
        NULL,
        $uri,
        $url,
        $these_options,
        $result,
        NULL,
      );
      $return[$url] = FALSE;

      // Stop processing this request as we have encountered an error.
      continue;
    }

    // Use a sync or async connection.
    $flags = httprl_set_connection_flag($these_options, $uri);

    // Set basic authorization header if needed.
    httprl_basic_auth($uri, $these_options);

    // If any data is given, do the right things to this request so it works.
    httprl_handle_data($these_options);

    // Build the request string.
    $response = httprl_build_request_string($uri, $these_options);

    // Put all variables into an array for easy alterations.
    $connections[] = array(
      $socket,
      $flags,
      $uri,
      $url,
      $these_options,
      $result,
      $response,
    );
    $return[$url] = TRUE;
  }
  $results = array();
  foreach ($connections as $connection) {
    list($socket, $flags, $uri, $url, $options, $result, $response) = $connection;
    $result->request = $response;
    $result->options = $options;
    $result->socket = $socket;
    $result->flags = $flags;
    $result->uri = $uri;
    $result->running_time = 0;
    $results[] = $result;
  }
  if ($full_bootstrap) {

    // Allow other programs to alter the connections before they are made.
    // run hook_httprl_request_alter().
    drupal_alter('httprl_request', $results);
  }
  if (httprl_send_request($results)) {
    return $return;
  }
  else {
    return FALSE;
  }
}