Return to README CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / sapi / apache_hooks

php

    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!