Issue #2222555 by mikeytown2: Show the delay in the admin screen; add description...
[project/httprl.git] / README.txt
1
2 ------------------------------------------------
3 HTTP PARALLEL REQUEST & THREADING LIBRARY MODULE
4 ------------------------------------------------
5
6
7 CONTENTS OF THIS FILE
8 ---------------------
9
10  * About HTTPRL
11  * Requirements
12  * Configuration
13  * API Overview
14  * Technical Details
15  * Code Examples
16
17
18 ABOUT HTTPRL
19 ------------
20
21 http://drupal.org/project/httprl
22
23 HTTPRL is a flexible and powerful HTTP client implementation. Correctly handles
24 GET, POST, PUT or any other HTTP requests & the sending of data. Issue blocking
25 or non-blocking requests in parallel. Set timeouts, max simultaneous connection
26 limits, chunk size, and max redirects to follow. Can handle data with
27 content-encoding and transfer-encoding headers set. Correctly follows
28 redirects. Option to forward the referrer when a redirect is found. Cookie
29 extraction and parsing into key value pairs. Can multipart encode data so files
30 can easily be sent in a HTTP request. Will emulate a range request if the server
31 does not support range requests.
32
33
34 REQUIREMENTS
35 ------------
36
37 Requires PHP 5. The following functions must be available on the server:
38  * stream_socket_client
39  * stream_select
40  * stream_set_blocking
41  * stream_get_meta_data
42  * stream_socket_get_name
43 Some hosting providers disable these functions; but they do come standard with
44 PHP 5.
45
46
47 CONFIGURATION
48 -------------
49
50 Settings page is located at:
51 6.x: admin/settings/httprl
52 7.x: admin/config/development/httprl
53
54  * IP Address to send all self server requests to. If left blank it will use the
55    same server as the request. If set to -1 it will use the host name instead of
56    an IP address. This controls the output of httprl_build_url_self().
57  * Enable background callbacks. If disabled all background_callback keys will
58    be turned into callback & httprl_queue_background_callback will return NULL
59    and not queue up the request. Note that background callbacks will
60    automatically be disabled if the site is in maintenance mode.
61
62
63 API OVERVIEW
64 ------------
65
66 Issue HTTP Requests:
67 httprl_build_url_self()
68  - Helper function to build an URL for asynchronous requests to self. Note that
69    you should set the Host name in the headers when using this.
70 httprl_request()
71  - Queue up a HTTP request in httprl_send_request().
72 httprl_send_request()
73  - Perform many HTTP requests.
74
75 Create and use a thread:
76 httprl_queue_background_callback()
77  - Queue a special HTTP request (used for threading) in httprl_send_request().
78
79 Other Functions:
80 httprl_is_background_callback_capable()
81  - See if httprl can issue a background callback.
82 httprl_background_processing()
83  - Output text, close connection, continue processing in the background.
84 httprl_strlen()
85  - Get the length of a string in bytes.
86 httprl_glue_url()
87  - Alt to http_build_url().
88 httprl_get_server_schema()
89  - Return the server schema (http or https).
90 httprl_pr()
91  - Pretty print data.
92 httprl_fast403()
93  - Issue a 403 and exit.
94
95
96 TECHNICAL DETAILS
97 -----------------
98
99 Using stream_select() HTTPRL will send http requests out in parallel. These
100 requests can be made in a blocking or non-blocking way. Blocking will wait for
101 the http response; Non-Blocking will close the connection not waiting for the
102 response back. The API for httprl is similar to the Drupal 7 version of
103 drupal_http_request().
104
105 HTTPRL can be used independent of drupal. For basic operations it doesn't
106 require any built in drupal functions.
107
108
109 CODE EXAMPLES
110 -------------
111
112 See examples/httprl.examples.php for code examples.