Return to README CVS log | Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / sapi / apache_hooks |
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!