Annotation of embedaddon/php/sapi/apache_hooks/README, revision 1.1.1.1
1.1 misho 1: This is very beta documentation. Clearly better stuff can and will follow.
2:
3: INTRO:
4:
5: apache_hooks is a full super-set enhancement of the apache 1.3 sapi that allows for
6: php code to be run on the apache request object at every stage of the apache
7: request. It supports all of the apache 1.3 sapi commands and configurations, and
8: additionally supports the following httpd.conf directives:
9:
10:
11: HTTPD.CONF DIRECTIEVS:
12:
13: phpRequire /path/to/file = requires a file at the beginning of an
14: initial apache request
15:
16: phpUriHandler /path/to/file = registers a hook that will run the
17: specified file at the uri translation stage of the apache request
18: phpUriHandler Class::Method = registers a hook to run Class::Method at
19: the uri translation stage of the apache request
20:
21: phpPostReadHandler /path/to/file = hook for post-read phase
22: phpPostReadHandlerMethod Class::Method
23:
24: phpHeaderHandler = hook for header parsing phase
25: phpHeaderHandlerMethod
26:
27: phpAuthHandler = hook for authentication phase
28: phpAuthHandlerMethod
29:
30: phpAccessHandler = hook for access control phase
31: phpAccessHandlerMethod
32:
33: phpTypeHandler = hook for Type Checking phase
34: phpTypeHandlerMethod
35:
36: phpFixupHandler = hook for 'fixup' phase
37: phpFixupHandlerMethod
38:
39: phpLoggerHandler = hook for logging phase
40: phpLoggerHandlerMethod
41:
42: AddHandler php-script = set's up a special type handler
43: phpResponseHandler /path/to/file = sets file to be called to handle
44: response phase
45: phpResponseHandlerMethod Class::Method
46:
47:
48: All handlers may be stacked, i.e. you can list multiple handler directives
49: in a single scope and they will be run in order.
50:
51:
52: EXAMPLES:
53:
54: So, to set up a 'hello world' location handler (so that any request to
55: /hello/* returns hello world) you can:
56:
57: phpRequire /tmp/setup.php
58: <Location /hello>
59: AddHandler php-script
60: phpResponseHandlerMethod Hello::World
61: </Location>
62:
63: with
64: #/tmp/setup.php
65: <?
66: class Hello {
67: function World() {
68: global $request;
69: $request->send_http_header();
70: echo "Hello World";
71: }
72: }
73: ?>
74:
75: $request is the apache request. It is instantiated at all stages
76: automatically. The methods of that class are:
77:
78: getallheaders
79: args
80: boundary
81: content_encoding
82: content_type
83: filename
84: handler
85: hostname
86: method
87: path_info
88: protocol
89: status_line
90: the_request
91: unparsed_uri
92: uri
93: allowed
94: bytes_sent
95: chunked
96: content_length
97: header_only
98: method_number
99: mtime
100: no_cache
101: no_local_copy
102: proto_num
103: proxyreq
104: read_body
105: remaining
106: request_time
107: status
108: headers_in
109: headers_out
110: err_headers_out
111: auth_name
112: auth_type
113: basic_auth_pw
114: discard_request_body
115: is_initial_req
116: meets_conditions
117: remote_host
118: satisfies
119: server_port
120: set_etag
121: set_last_modified
122: some_auth_required
123: update_mtime
124: send_http_header
125: basic_http_header
126: send_header_field
127: send_http_trace
128: send_http_options
129: send_error_response
130: set_content_length
131: set_keepalive
132: rputs
133: log_error
134: lookup_uri
135: lookup_file
136: method_uri
137: run
138: internal_redirect
139:
140:
141: These all wrap the ap_* apache EXPORT_API functions using the same
142: semantics (and are also the same as the Apache::Request methods in
143: mod_perl if you are familiar with that)
144:
145: So, a uri handler to redirect all non-local traffic to /404.php (an
146: error page) would be
147:
148: phpUriHandler /tmp/uri.php
149:
150: #/tmp/uri.php
151: <?
152: if($REMOTE_ADDR != '127.0.0.1') {
153: $request->uri('/404.php');
154: }
155: return OK;
156: ?>
157:
158: It's important to note that since this is called from the uri
159: translations phase, this validation is performed for every request to
160: the server, not just for php pages.
161:
162: Also, scope is shared between all the hooks. So in the above, we could
163: merge the two and do something like:
164:
165: #/tmp/uri.php
166: <?
167: if($REMOTE_ADDR != '127.0.0.1') {
168: $whoami = 'Stranger';
169: }
170: else {
171: $whoami = 'Friend';
172: }
173: return DECLINED; # because we're not redirecting, just messing around
174: ?>
175:
176: and then:
177:
178: #/tmp/setup.php
179: <?
180: class Hello {
181: function World() {
182: global $request;
183: global $whoami;
184: $request->send_http_header();
185: echo "Hello $whoami";
186: }
187: }
188: ?>
189:
190: These variables are also in the same scope as a script if your script is
191: being handled by the standard application/x-httpd-php handler.
192:
193: This allows you to make decisions and pass data between your handlers
194: and scripts at all stages.
195:
196: The above are clearly trite examples, but hopefully give you a starting
197: point.
198:
199: One note: all handlers can be validly re-entered 'in sub-requests'.
200: For this reason you should not define functions/classes here without
201: anti-redefinition guards (I would just recommend putting them in an
202: include and using include_one). This is not true for phpRequire, which
203: is only entered once, at the main request, and so it is safe to make
204: function/class declarations there (in fact that's what it's for).
205:
206: Hope that helps!
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / sapi / apache_hooks