Apache2::RequestUtil - Perl API for Apache request record utils

  use Apache2::RequestUtil ();

  # add httpd config dynamically
  $r->add_config(['require valid-user']);

  # dump the request object as a string
  print $r->as_string();

  # default content_type
  $content_type = $r->default_type();

  # get PerlSetVar/PerlAddVar values
  @values = $r->dir_config->get($key);

  # get server docroot
  $docroot = $r->document_root();

  # set server docroot
  $r->document_root($new_root);

  # what are the registered perl handlers for a given phase
  my @handlers = @{ $r->get_handlers('PerlResponseHandler') || [] };

  # push a new handler for a given phase
  $r->push_handlers(PerlCleanupHandler => \&handler);

  # set handlers for a given phase (resetting previous values)
  $r->set_handlers(PerlCleanupHandler => []);

  # what's the request body limit
  $limit = $r->get_limit_req_body();

  # server and port names
  $server = $r->get_server_name();
  $port   = $r->get_server_port();

  # what string Apache is going to send for a given status code
  $status_line = Apache2::RequestUtil::get_status_line(4);

  # are we in the main request?
  $is_initial = $r->is_initial_req();

  # directory level PerlOptions flags lookup
  $r->subprocess_env unless $r->is_perl_option_enabled('SetupEnv');

  # current <Location> value
  $location = $r->location();

  # merge a <Location> container in a request object
  $r->location_merge($location);

  # create a new Apache2::RequestRec object
  $r = Apache2::RequestRec->new($c);

  # tell the client not to cache the response
  $r->no_cache($boolean);

  # share perl objects like $r->notes
  $r->pnotes($key => [$obj1, $obj2]);

  # get HTML signature
  $sig = $r->psignature($prefix);

  # get the global request object (requires PerlOptions +GlobalRequest)
  $r = Apache2::RequestUtil->request;

  # insert auth credentials into the request as if the client did that
  $r->set_basic_credentials($username, $password);

  # slurp the contents of $r->filename
  my $content = ${ $r->slurp_filename() };

  # terminate the current child after this request
  $r->child_terminate();

CWApache2::RequestUtil provides the Apache request object utilities API.

Dynamically add Apache configuration at request processing runtime:

  $r->add_config($lines);
  $r->add_config($lines, $override);

ret: no return value

since: 2.0.00

See also: CW$s->add_config

For example:

  use Apache2::ServerUtil ();
  $r->add_config(['require valid-user']);

  $dump = $r->as_string();

since: 2.0.00

Dumps various request and response headers (mainly useful for debugging) Terminate the current worker process as soon as the current request is over

  $r->child_terminate();

ret: no return value

since: 2.0.00

This method is not supported in threaded MPMs Retrieve the value of the DefaultType directive for the current request. If not set CWtext/plain is returned.

  $content_type = $r->default_type();

since: 2.0.00

CW$r->dir_config() provides an interface for the per-directory variable specified by the CWPerlSetVar and CWPerlAddVar directives, and also can be manipulated via the CWAPR::Table methods.

  $table  = $r->dir_config();
  $value  = $r->dir_config($key);
  @values = $r->dir_config->get($key);
  $r->dir_config($key, $val);

ret: ...

Depends on the passed arguments, see further discussion

since: 2.0.00

The keys are case-insensitive.

  $apr_table = $r->dir_config();

dir_config() called in a scalar context without the CW$key argument returns a HASH reference blessed into the CWAPR::Table class. This object can be manipulated via the CWAPR::Table methods. For available methods see the CWAPR::Table manpage.

  $value = $r->dir_config($key);

If the CW$key argument is passed in the scalar context only a single value will be returned. Since the table preserves the insertion order, if there is more than one value for the same key, the oldest value assosiated with the desired key is returned. Calling in the scalar context is also much faster, as it'll stop searching the table as soon as the first match happens.

  @values = $r->dir_config->get($key);

To receive a list of values you must use CWget() method from the CWAPR::Table class.

  $r->dir_config($key => $val);

If the CW$key and the CW$val arguments are used, the set() operation will happen: all existing values associated with the key CW$key (and the key itself) will be deleted and CW$value will be placed instead.

  $r->dir_config($key => undef);

If CW$val is undef the unset() operation will happen: all existing values associated with the key CW$key (and the key itself) will be deleted. Retrieve the document root for this server

  $docroot = $r->document_root();
  $docroot = $r->document_root($new_root);

since: 2.0.00

Returns a reference to a list of handlers enabled for a given phase.

  $handlers_list = $r->get_handlers($hook_name);

since: 2.0.00

See also: CW$s->add_config

For example:

A list of handlers configured to run at the response phase:

  my @handlers = @{ $r->get_handlers('PerlResponseHandler') || [] };

  $limit = $r->get_limit_req_body();

since: 2.0.00

Get the current request's server name

  $server = $r->get_server_name();

since: 2.0.00

For example, consruct a hostport string:

  use Apache2::RequestUtil ();
  my $hostport = join ':', $r->get_server_name, $r->get_server_port;

  $port = $r->get_server_port();

since: 2.0.00

For example, consruct a hostport string:

  use Apache2::RequestUtil ();
  my $hostport = join ':', $r->get_server_name, $r->get_server_port;

  $status_line = Apache2::RequestUtil::get_status_line($status);

since: 2.0.00

For example:

  use Apache2::RequestUtil ();
  print Apache2::RequestUtil::get_status_line(4);

will print:

  400 Bad Request

  $is_initial = $r->is_initial_req();

since: 2.0.00

check whether a directory level CWPerlOptions flag is enabled or not.

  $result = $r->is_perl_option_enabled($flag);

since: 2.0.00

For example to check whether the CWSetupEnv option is enabled for the current request (which can be disabled with CWPerlOptions -SetupEnv) and populate the environment variables table if disabled:

  $r->subprocess_env unless $r->is_perl_option_enabled('SetupEnv');

See also: PerlOptions and the equivalent function for server level PerlOptions flags. Get the path of the <Location> section from which the current CWPerl*Handler is being called.

  $location = $r->location();

since: 2.0.00

Merge a given CW<Location< container into the current request object:

  $ret = $r->location_merge($location);

  <Location /foo>
      ...
  </Location>

since: 2.0.00

Useful for insertion of a configuration section into a custom CWApache2::RequestRec object, created via the CWApache2::RequestRec->new() method. See for example the Command Server protocol example. Create a new CWApache2::RequestRec object.

  $r = Apache2::RequestRec->new($c);
  $r = Apache2::RequestRec->new($c, $pool);

since: 2.0.00

It's possible to reuse the HTTP framework features outside the familiar HTTP request cycle. It's possible to write your own full or partial HTTP implementation without needing a running Apache server. You will need the CWApache2::RequestRec object in order to be able to reuse the rich functionality supplied via this object.

See for example the Command Server protocol example which reuses HTTP AAA model under non-HTTP protocol. Add/remove cache control headers:

  $prev_no_cache = $r->no_cache($boolean);

  Pragma: no-cache
  Cache-control: no-cache

since: 2.0.00

This method should be invoked before any response data has been sent out. Share Perl variables between Perl HTTP handlers

  $old_val  = $r->pnotes($key => $val);
  $val      = $r->pnotes($key);
  $hash_ref = $r->pnotes();

ret: (3 different possible values)

if both, CW$key and CW$val are passed the previous value for CW$key is returned if such existed, otherwise CWundef is returned. if only CW$key is passed, the current value for the given key is returned. if no arguments are passed, a hash reference is returned, which can then be directly accessed without going through the CWpnotes() interface.

since: 2.0.00

This method provides functionality similar to (CWApache2::RequestRec::notes), but values can be any Perl variables. That also means that it can be used only between Perl modules.

The values get reset automatically at the end of each HTTP request.

Examples:

Set a key/value pair:

  $r->pnotes(foo => [1..5]);

Get the value:

  $val = $r->pnotes("foo");

CW$val now contains an array ref containing 5 elements (CW1..5).

Now change the existing value:

  $old_val = $r->pnotes(foo => ['a'..'c']);
  $val = $r->pnotes("foo");

CW$old_val now contains an array ref with 5 elements (CW1..5) and CW$val contains an array ref with 3 elements CW'a', CW'b', CW'c'.

Alternatively you can access the hash reference with all pnotes values:

  $pnotes = $r->pnotes;

Now we can read what's in there for the key foo:

  $val = $pnotes->{foo};

and as before CW$val still gives us an array ref with 3 elements CW'a', CW'b', CW'c'.

Now we can add elements to it:

  push @{ $pnotes{foo} }, 'd'..'f';

and we can try to retrieve them using the hash and non-hash API:

  $val1 = $pnotes{foo};
  $val2 = $r->pnotes("foo");

Both CW$val1 and CW$val2 contain an array ref with 6 elements (letters 'a' to 'f').

Finally to reset an entry you could just assign CWundef as a value:

  $r->pnotes(foo => undef);

but the entry for the key foo still remains with the value CWundef. If you really want to completely remove it, use the hash interface:

  delete $r->pnotes->{foo};

  $sig = $r->psignature($prefix);

since: 2.0.00

Get/set the ( CWApache2::RequestRec object ) object for the current request.

  $r = Apache2::RequestUtil->request;
       Apache2::RequestUtil->request($new_r);

since: 2.0.00

The get-able part of this method is only available if CWPerlOptions +GlobalRequest is in effect or if CWApache2->request($new_r) was called earlier. So instead of setting CWPerlOptions +GlobalRequest, one can set the global request from within the handler. Add one or more handlers to a list of handlers to be called for a given phase.

  $ok = $r->push_handlers($hook_name => \&handler);
  $ok = $r->push_handlers($hook_name => ['Foo::Bar::handler', \&handler2]);

since: 2.0.00

See also: CW$s->add_config Note that to push input/output filters you have to use CWApache2::Filter methods: CWadd_input_filter and CWadd_output_filter.

Examples:

A single handler:

  $r->push_handlers(PerlResponseHandler => \&handler);

Multiple handlers:

  $r->push_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);

Anonymous functions:

  $r->push_handlers(PerlLogHandler => sub { return Apache2::Const::OK });

  $r->set_basic_credentials($username, $password);

ret: no return value

since: 2.0.00

See for example the Command Server protocol example which reuses HTTP AAA model under non-HTTP protocol. Set a list of handlers to be called for a given phase. Any previously set handlers are forgotten.

  $ok = $r->set_handlers($hook_name => \&handler);
  $ok = $r->set_handlers($hook_name => ['Foo::Bar::handler', \&handler2]);
  $ok = $r->set_handlers($hook_name => []);
  $ok = $r->set_handlers($hook_name => undef);

since: 2.0.00

See also: CW$s->add_config

Examples:

A single handler:

  $r->set_handlers(PerlResponseHandler => \&handler);

Multiple handlers:

  $r->set_handlers(PerlFixupHandler => ['Foo::Bar::handler', \&handler2]);

Anonymous functions:

  $r->set_handlers(PerlLogHandler => sub { return Apache2::Const::OK });

Reset any previously set handlers:

  $r->set_handlers(PerlCleanupHandler => []);

or

  $r->set_handlers(PerlCleanupHandler => undef);

  $content_ref = $r->slurp_filename($tainted);

since: 2.0.00

Note that if you assign to CW$r->filename you need to update its stat record.

mod_perl 2.0 documentation.

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.

The mod_perl development team and numerous contributors.