Annotation of embedaddon/php/sapi/apache_hooks/README, revision 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