You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by mo...@apache.org on 2002/04/25 09:01:05 UTC
cvs commit: modperl-docs/src/start/tips config.pod favicon.pod handler.pod logging.pod registry.pod
moseley 02/04/25 00:01:02
Modified: src/start config.cfg
Added: src/start/tips config.pod favicon.pod handler.pod
logging.pod registry.pod
Log:
Revision Changes Path
1.3 +5 -4 modperl-docs/src/start/config.cfg
Index: config.cfg
===================================================================
RCS file: /home/cvs/modperl-docs/src/start/config.cfg,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- config.cfg 24 Apr 2002 04:15:27 -0000 1.2
+++ config.cfg 25 Apr 2002 07:01:01 -0000 1.3
@@ -12,10 +12,11 @@
hidden => [
chapters => [
qw(
- tips/registry.html
- tips/handler.html
- tips/logging.html
- tips/config.html
+ tips/registry.pod
+ tips/handler.pod
+ tips/logging.pod
+ tips/config.pod
+ tips/favicon.pod
)
],
],
1.1 modperl-docs/src/start/tips/config.pod
Index: config.pod
===================================================================
=head1 NAME
Configure Apache with Perl Example
=head1 Configure virtual hosts
With mod_perl, Perl code can be embedded directly in the Apache configuration file.
Perl in httpd.conf is commonly used to dynamically configure Apache, but anything from
URL translation to content generation can be accomplished directly in the configuation file.
This example reads configuration settings from a text file and configures Apache's
virtual hosts.
The httpd.conf setup:
NameVirtualHost 192.168.0.1:80
<Perl>
open(HOSTS,'/etc/apache/vhosts.txt')
or die "Failed to open vhosts.txt: $!";
while (<HOSTS>) {
my %config;
my @params = qw/ServerName DocumentRoot ErrorLog TransferLog ServerAdmin/;
@config{ @params } = split /\t/;
$config{Directory}{$config{DocumentRoot}} = { Allow => 'from all'};
push @{$VirtualHost{'192.168.0.1:80'}}, \%config;
}
close HOSTS;
</Perl>
See L<The Guide|guide::config/Apache_Configuration_in_Perl>
for other examples of configuring Apache with mod_perl.
=for html
<a class="more" href="../index.html#config">« back</a>
1.1 modperl-docs/src/start/tips/favicon.pod
Index: favicon.pod
===================================================================
=head1 NAME
Example PerlTransHandler
=head1 Using mod_perl to rewrite URLs
Anyone that's looked at web logs will quickly see the usefulness of this little
mod_perl script. It catches all requests for favicon.ico and rewrites the request
to point to a vaild location. No more logs full of 404 errors.
This example is adapted from the L<mod_perl Devekioer's Cookbook|http://modperlcookbook.com>, chapter 12.
package Cookbook::Favicon;
use Apache::Constants qw(DECLINED);
use strict;
sub handler {
my $r = shift;
$r->uri('/images/favicon.ico')
if $r->uri =~ m!/favicon\.ico$!
return DECLINED;
}
1;
And configure in F<httpd.conf> with:
PerlModule Cookbook::Favicon
PerlTransHandler Cookbook::Favicon
Although this example could easily be accomplished with Apache's mod_rewrite module,
this example demonstrates how easy it is to rewrite URLs programatically, using the
power of Perl.
=for html
<a class="more" href="../index.html#handler">« back</a>
=cut
1.1 modperl-docs/src/start/tips/handler.pod
Index: handler.pod
===================================================================
=head1 NAME
Content Handler Example
=head1 Creating a content handler with mod_perl
Handlers are simply perl subroutines called by the server at various stages of the HTTP request cycle.
A content handler is a subroutine that is called by the response phase. Handlers, are
typically created as a perl modules, separate files store in a library, and accessable via perl's @INC array.
For example, here's an example that returns a greeting and the current local time.
package My::Greeting;
use strict;
sub handler {
my $r = shift;
my $now = scalar localtime;
my $server_name = $r->server->server_hostname;
$r->send_http_header('text/plain');
print <<EOT;
Thanks for visiting $server_name.
The local time is $now
EOT
return $Apache::Constants::OK;
}
1; # modules must return true
Save the above as a file file in your perl library (e.g. My/Greeting.pm).
Now, to return the above greeting when the URL /hello is visited on your server:
<location /hello>
SetHandler perl-script
PerlHandler My::Greeting
</location>
For a more in-depth explanation of creating mod_perl handlers see
L<Documentation|"../../docs/index.html">.
The L<mod_perl Guide|"../../docs/1.0/guide/index.html"> is also recommended
reading.
=for html
<a class="more" href="../index.html#handler">« back</a>
1.1 modperl-docs/src/start/tips/logging.pod
Index: logging.pod
===================================================================
=head1 NAME
Log Handler Example
=head1 Creating a PerlLogHandler
Every request phase can be controlled using mod_perl. Here's an example
of a PerlLogHandler. The PerlLogHandler is one of the last phases of the request
cycle.
This example sends mail when a request is made to the /private section of your
web space. A more common use of a PerlLogHandler might be to track hits on a
specific set of URLs, or to write logging data to a relational database.
package My::Notify;
use strict;
use Apache::Constants(':common');
use Mail::Send;
sub handler {
my $r = shift;
my $email = $r->server->server_admin || return DECLINED;
my $mail = Mail::Send->new(
To => $email,
Subject => "mod_perl Notification",
);
my $file = $r->filename;
my $fh = $mail->open;
$fh->print("File '$file' was accessed");
$fh->close;
return DECLINED; # let apache write to the lot
}
1; # modules must return true
The httpd.conf setup:
<location /private>
SetHandler perl-script
PerlLogHandler My::Notify
</location>
=for html
<a class="more" href="../index.html#logging">« back</a>
1.1 modperl-docs/src/start/tips/registry.pod
Index: registry.pod
===================================================================
=head1 NAME
Apache::Registry Example
=head1 Running CGI scripts with mod_perl
Existing CGI scripts will run much faster under mod_perl.
And converting existing CGI scripts to run under mod_perl is easy.
For example, here's an existing CGI script called F<hello.cgi>.
#!/usr/local/bin/perl -w
use strict;
use CGI;
my $q = CGI->new;
print $q->header,
$q->start_html,
$q->h1('Hello World!'),
$q->end_html;
This script can now be run as-is under Apache::Registry by using the
following configuration in httpd.conf:
<files hello.cgi>
SetHandler perl-script
PerlHandler Apache::Registry
Options ExecCGI
</files>
That's basically it. Your scripts do need to be well coded, but there's even the
Apache::PerlRun module to help with those "less clean" programs.
So how much faster do scripts run under Apache::Registry? Obviously, it depends
on the script, but the "hello.cgi" script above ran
at 7.3 requests per second as a CGI script and 243.0 requests per second with Apache::Registry.
=for html
<small>Tested with Apache Benchmark (ab -n 1000) on Linux PIII-550Mhz, Apache version 1.3.20</small>
For more information on running CGI scripts under mod_perl please see
L<mod_perl FAQs|"../../docs/1.0/faqs/index.html">.
=for html
<a class="more" href="../index.html#registry">« back</a>
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org
Re: cvs commit: modperl-docs/src/start/tips config.pod favicon.pod
handler.pod logging.pod registry.pod
Posted by Stas Bekman <st...@stason.org>.
Bill Moseley wrote:
> At 03:56 PM 4/25/2002 +0800, Stas Bekman wrote:
>
>
>
>>> For more information on running CGI scripts under mod_perl please see
>>> L<mod_perl FAQs|"../../docs/1.0/faqs/index.html">.
>>
>>Guys, we shoundn't link to /faqs in most cases. The info from most of
>>the mod_perl faqs is in the guide. A few faqs which aren't in the guide
>>(e.g. the cvs faq). There are two sources of information for 1.x, which
>>is the API pods and the user docs (the guide). If something is broken
>>and missing, we need to fix/improve only one document. The multiplicity
>>just confuses users and makes them read more.
>
>
> I thought about that.
>
> My reasoning was that the that part of What is mod_perl is just showing an
> example of how a Registry script looks (how easy it is). The FAQs seemed
> like the next step in the journey toward the hard-core docs. The FAQ
> section has "First steps needed to use mod_perl as a CGI replacement" and
> "Running CGI scripts under mod_perl" which are both specifically about
> Registry scripts, what that section is talking about. So it seemed like a
> natural progression.
Point it directly to the section discussing this in the guide.
getwet.pod is another good place to point to.
> There's a lot of duplication, of course, between the faqs and guide about
> running Registry scripts. Hard to know which docs will work better for
> each new mod_perl user. I think those little examples should probably link
> to the Guide and the Faqs, but maybe to those two specific faqs listed
> above. (I thought that it would be easy enough for someone to spot the CGI
> porting faqs, at the same time see something else that catches the eye.)
>
> [ I don't know about everyone else, but I tend to read FAQs first on a new
> program. They often don't make sense without reading the docs, but it
> gives me a "heads up" of what topics to pay special attention to when
> reading the docs.]
>
> See any reason why we couldn't point to the two faqs and to the guide?
The reason is this: the faqs are already included in the guide. The faqs
aren't as complete as the guide. And they weren't maintained for at
least 2 years. And they only add to the confusion. If something is not
satisfying in the guide this should be fixed and keep concentrating the
efforts on one document. The guide *is* the FAQ, but a very big one. I
think 50% of the material are just answers to the questions asked on the
list, if not more.
I think we should simply remove from the website the faqs that are
duplicates, first asking the permission of their original authors. This
will solve the confusion all together.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: cvs commit: modperl-docs/src/start/tips config.pod
favicon.pod handler.pod logging.pod registry.pod
Posted by Bill Moseley <mo...@hank.org>.
At 03:56 PM 4/25/2002 +0800, Stas Bekman wrote:
>> For more information on running CGI scripts under mod_perl please see
>> L<mod_perl FAQs|"../../docs/1.0/faqs/index.html">.
>
>Guys, we shoundn't link to /faqs in most cases. The info from most of
>the mod_perl faqs is in the guide. A few faqs which aren't in the guide
>(e.g. the cvs faq). There are two sources of information for 1.x, which
>is the API pods and the user docs (the guide). If something is broken
>and missing, we need to fix/improve only one document. The multiplicity
>just confuses users and makes them read more.
I thought about that.
My reasoning was that the that part of What is mod_perl is just showing an
example of how a Registry script looks (how easy it is). The FAQs seemed
like the next step in the journey toward the hard-core docs. The FAQ
section has "First steps needed to use mod_perl as a CGI replacement" and
"Running CGI scripts under mod_perl" which are both specifically about
Registry scripts, what that section is talking about. So it seemed like a
natural progression.
There's a lot of duplication, of course, between the faqs and guide about
running Registry scripts. Hard to know which docs will work better for
each new mod_perl user. I think those little examples should probably link
to the Guide and the Faqs, but maybe to those two specific faqs listed
above. (I thought that it would be easy enough for someone to spot the CGI
porting faqs, at the same time see something else that catches the eye.)
[ I don't know about everyone else, but I tend to read FAQs first on a new
program. They often don't make sense without reading the docs, but it
gives me a "heads up" of what topics to pay special attention to when
reading the docs.]
See any reason why we couldn't point to the two faqs and to the guide?
Bill Moseley
mailto:moseley@hank.org
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org
Re: cvs commit: modperl-docs/src/start/tips config.pod favicon.pod
handler.pod logging.pod registry.pod
Posted by Stas Bekman <st...@stason.org>.
moseley@apache.org wrote:
> moseley 02/04/25 00:01:02
>
> Modified: src/start config.cfg
> Added: src/start/tips config.pod favicon.pod handler.pod
> logging.pod registry.pod
> Log:
> Index: registry.pod
> ===================================================================
...
> =for html
> <small>Tested with Apache Benchmark (ab -n 1000) on Linux PIII-550Mhz, Apache version 1.3.20</small>
>
> For more information on running CGI scripts under mod_perl please see
> L<mod_perl FAQs|"../../docs/1.0/faqs/index.html">.
Guys, we shoundn't link to /faqs in most cases. The info from most of
the mod_perl faqs is in the guide. A few faqs which aren't in the guide
(e.g. the cvs faq). There are two sources of information for 1.x, which
is the API pods and the user docs (the guide). If something is broken
and missing, we need to fix/improve only one document. The multiplicity
just confuses users and makes them read more.
therefore that link should be L<guide|guide::porting>
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org