Module ngx_http_perl_module
ngx_http_perl_module
模块用于在 Perl 中实现位置和变量处理程序,并将 Perl 调用插入 SSI。
默认情况下未构建此模块,应使用--with-http_perl_module
配置参数启用它。
Note
此模块要求Perl 5.6.1 或更高版本。 C 编译器应与用于构建 Perl 的编译器兼容。
Known Issues
该模块是实验性的,警告购买者适用。
为了使 Perl 在重新配置期间重新编译已修改的模块,应使用-Dusemultiplicity=yes
或-Dusethreads=yes
参数来构建它。另外,要使 Perl 在运行时泄漏较少的内存,应使用-Dusemymalloc=no
参数构建它。要在已经构建的 Perl 中检查这些参数的值(在示例中指定了首选值),请运行:
$ perl -V:usemultiplicity -V:usemymalloc
usemultiplicity='define';
usemymalloc='n';
请注意,在使用新的-Dusemultiplicity=yes
或-Dusethreads=yes
参数重建 Perl 之后,所有二进制 Perl 模块也必须重建-它们将仅停止使用新的 Perl。
每次重新配置后,主进程和然后的工作进程的大小都有可能增加。如果主进程增长到不可接受的大小,则可以应用live upgrade过程,而无需更改可执行文件。
当 Perl 模块执行长时间运行的操作(例如解析域名,连接到另一台服务器或查询数据库)时,将不会处理分配给当前工作进程的其他请求。因此,建议仅执行具有可预测且执行时间短的操作,例如访问本地文件系统。
Example Configuration
http {
perl_modules perl/lib;
perl_require hello.pm;
perl_set $msie6 '
sub {
my $r = shift;
my $ua = $r->header_in("User-Agent");
return "" if $ua =~ /Opera/;
return "1" if $ua =~ / MSIE [6-9]\.\d+/;
return "";
}
';
server {
location / {
perl hello::handler;
}
}
perl/lib/hello.pm
模块:
package hello;
use nginx;
sub handler {
my $r = shift;
$r->send_http_header("text/html");
return OK if $r->header_only;
$r->print("hello!\n
");
if (-f $r->filename or -d _) {
$r->print($r->uri, " exists!\n");
}
return OK;
}
1;
__END__
Directives
Syntax: | perl module::function|'sub { ... }'; |
Default: | — |
Context: | location , limit_except |
为给定位置设置一个 Perl 处理程序。
Syntax: | perl_modules path; |
Default: | — |
Context: | http |
为 Perl 模块设置附加路径。
Syntax: | perl_require module; |
Default: | — |
Context: | http |
定义将在每次重新配置期间加载的模块的名称。可以存在多个perl_require
指令。
Syntax: | perl_set $variable module::function|'sub { ... }'; |
Default: | — |
Context: | http |
为指定的变量安装一个 Perl 处理程序。
从 SSI 调用 Perl
调用 Perl 的 SSI 命令具有以下格式:
<!--# perl sub="module::function" arg="parameter1" arg="parameter2" ...
-->
$ r 请求对象方法
-
$r->args
- 返回请求参数。
-
$r->filename
- 返回与请求 URI 相对应的文件名。
-
$r->has_request_body(handler)
- 如果请求中没有主体,则返回 0.如果有正文,则为请求设置指定的处理程序,并返回 1.读取请求主体后,nginx 将调用指定的处理程序。请注意,处理函数应通过引用传递。例:
package hello;
use nginx;
sub handler {
my $r = shift;
if ($r->request_method ne "POST") {
return DECLINED;
}
if ($r->has_request_body(\&post)) {
return OK;
}
return HTTP_BAD_REQUEST;
}
sub post {
my $r = shift;
$r->send_http_header;
$r->print("request_body: \"", $r->request_body, "\"
");
$r->print("request_body_file: \"", $r->request_body_file, "\"
\n");
return OK;
}
1;
__END__
-
$r->allow_ranges
- 发送响应时启用字节范围的使用。
-
$r->discard_request_body
- 指示 nginx 放弃请求主体。
-
$r->header_in(field)
- 返回指定的客户端请求 Headers 字段的值。
-
$r->header_only
- 确定是将整个响应还是仅将其 Headers 发送给客户端。
-
$r->header_out(field, value)
- 为指定的响应头字段设置一个值。
$r->internal_redirect(uri)
- 内部重定向到指定的
uri
。 Perl 处理程序执行完成后,发生实际的重定向。
Note
从 1.17.2 版开始,该方法接受转义的 URI,并支持重定向到命名位置。
-
$r->log_error(errno, message)
- 将指定的
message
写入error_log。如果errno
不为零,则错误代码及其描述将附加到消息中。
- 将指定的
-
$r->print(text, ...)
- 将数据传递给客户端。
-
$r->request_body
- 如果尚未将客户请求主体写入临时文件,则返回该请求主体。为确保客户端请求主体在内存中,其大小应受client_max_body_size限制,并应使用client_body_buffer_size设置足够的缓冲区大小。
-
$r->request_body_file
- 返回带有客户端请求正文的文件名。处理后,应删除文件。要始终将请求正文写入文件,应启用client_body_in_file_only。
-
$r->request_method
- 返回客户端请求的 HTTP 方法。
-
$r->remote_addr
- 返回客户端 IP 地址。
-
$r->flush
- 立即将数据发送到客户端。
-
$r->sendfile(name[, offset[, length]])
- 将指定的文件内容发送到客户端。可选参数指定要传输的数据的初始偏移量和长度。实际的数据传输发生在 Perl 处理程序完成之后。
-
$r->send_http_header([type])
- 将响应 Headers 发送到客户端。可选的
type
参数设置“ Content-Type”响应头字段的值。如果值为空字符串,则不会发送“ Content-Type”头字段。
- 将响应 Headers 发送到客户端。可选的
-
$r->status(code)
- 设置响应码。
-
$r->sleep(milliseconds, handler)
- 设置指定的处理程序,并在指定时间内停止请求处理。同时,nginxcontinue 处理其他请求。在指定的时间过去之后,nginx 将调用已安装的处理程序。请注意,处理函数应通过引用传递。为了在处理程序之间传递数据,应使用
$r->variable()
。例:
- 设置指定的处理程序,并在指定时间内停止请求处理。同时,nginxcontinue 处理其他请求。在指定的时间过去之后,nginx 将调用已安装的处理程序。请注意,处理函数应通过引用传递。为了在处理程序之间传递数据,应使用
package hello;
use nginx;
sub handler {
my $r = shift;
$r->discard_request_body;
$r->variable("var", "OK");
$r->sleep(1000, \&next);
return OK;
}
sub next {
my $r = shift;
$r->send_http_header;
$r->print($r->variable("var"));
return OK;
}
1;
__END__
-
$r->unescape(text)
- 解码以“%XX”形式编码的文本。
-
$r->uri
- 返回请求 URI。
-
$r->variable(name[, value])
- 返回或设置指定变量的值。变量是每个请求的局部变量。