Sometimes you want to set some data in one of the early handler
phases and make it available in the latter handlers. For example, say
you set some data in a TransHandler and you want
the PerlHandler to be able to access it as well.
To accomodate this, Apache maintains a
"notes" table (tables are
implemented by the Apache::Table module) in the
request record. This table is simply a list of key/value pairs. One
handler can add its own key/value entry to the notes table, and later
the handler for a subsequent phase can retrieve the stored data.
Notes are maintained for the life of the current request and are
deleted when the transaction is finished. The notes(
) method is used to manipulate the notes table, and a note
set in one Apache module (e.g., mod_perl) can later be accessed in
another Apache module (e.g., mod_php).
The notes( ) method accepts only non-reference
scalars as its values, which makes this method unfit for storing
non-scalar variables. To solve this limitation mod_perl provides a
special method, called pnotes( ), that can accept
any kind of data structure as its values. However, the data set by
pnotes( ) is accessible only by mod_perl.
The note gets set when the key/value pair is provided. For example,
let's set a scalar value with a key
foo:
$r->notes("foo" => 10);
and a reference to a list as a value for the key
bar:
$r->pnotes("bar" => [1..10]);
Notes can be retrieved in two ways. The first way is to ask for the
value of the given key:
$foo = $r->notes("foo");
and:
@bar = @{ $r->pnotes("bar") || [ ] };
Note that we expect the note keyed as bar to be
a reference to a list.
The second method is to retrieve the whole notes table, which returns
a hash reference blessed into the Apache::Table
class:
Apache modules can pass information to each other via the notes
table. Here is an example of how a mod_perl authentication handler
can pass data to a mod_php content handler:
package Book::Auth;
...
sub handler {
my $r = shift;
...
$r->notes('answer',42);
...
}
1;
The mod_php content handler can retrieve this data as follows:
...
$answer = apache_note("answer");
...
You can use notes along with the subrequest methods
lookup_uri( ) and lookup_filename(
), too. To make it work, you need to set notes in the
subrequest object. For example, if you want to call a PHP subrequest
from within mod_perl and pass it a note, you can do it in the
following way:
my $subr = $r->lookup_uri('wizard.php');
$subr->notes('answer' => 42);
$subr->run;
As of the time of this writing you cannot access the parent request
tables from a PHP handler; therefore, you must set this note for the
subrequest. If the subrequest is running in the mod_perl domain,
however, you can always keep the notes in the parent request notes
table and access them via the main( ) method:
$r->main->notes('answer');
Similarly to the notes, you may want or need to use the Apache
environment variables table to pass the information between different
handlers.
If you know what environment variables you want to set before the
server starts and you know their respective values, you can use
SetEnv and PerlSetEnv in
httpd.conf, as explained in Chapter 4. These settings will always be the same for
all requests.
However, if you want to change or add some of the environment
variables during the processing of a request, because some other
handler that will be executed later relies on them, you should use
the subprocess_env( ) method.
<!--#if expr="$hour > 6 && $hour < 12" -->
Good morning!
<!--#elif expr="$hour >= 12 && $hour <= 18" -->
Good afternoon!
<!--#elif expr="$hour > 18 && $hour < 22" -->
Good evening!
<!--#else -->
Good night!
<!--#endif -->
and you have the following code in your mod_perl handler:
my $hour = (localtime)[2];
$r->subprocess_env(hour => $hour);
The page will nicely greet the surfer, picking the greeting based on
the current time. Of course, the greeting will be correct only for
users located in the same time zone as the server, but this is just a
simple example.
