模块 ngx_http_perl_module

Known Issues
Example Configuration
Directives
     perl
     perl_modules
     perl_require
     perl_set
Calling Perl from SSI
The $r Request Object Methods

ngx_http_perl_module模块用于在 Perl 中实现位置和变量处理程序,并将 Perl 调用插入到 SSI 中。

该模块不是默认构建的,需要通过 --with-http_perl_module 配置参数启用。

该模块需要 Perl版本 5.6.1 或更高版本。C 编译器应该与用于构建 Perl 的编译器兼容。

已知的问题

该模块是实验性的,买者自负。

为了让 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。

每次重新配置后,主进程和工作进程的大小可能会增加。如果主进程增长到不可接受的大小,则 可以应用 实时升级过程而不更改可执行文件。

当 Perl 模块执行长时间运行的操作(例如解析域名、连接到另一台服务器或查询数据库)时,分配给当前工作进程的其他请求将不会被处理。因此,建议仅执行可预测且执行时间短的操作,例如访问本地文件系统。

配置示例

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<br/>");

    if (-f $r->filename or -d _) {
        $r->print($r->uri, " exists!\n");
    }

    return OK;
}

1;
__END__

指令

句法: perl module::function|'sub { ... }';
默认:
语境: location,limit_except

为给定位置设置 Perl 处理程序。

句法: perl_modules path;
默认:
语境: http

为 Perl 模块设置附加路径​​。

句法: perl_require module;
默认:
语境: http

定义每次重新配置期间将加载的模块的名称。perl_require可以存在 多个指令。

句法: perl_set $variable module::function|'sub { ... }';
默认:
语境: 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, "\"<br/>");
    $r->print("request_body_file: \"", $r->request_body_file, "\"<br/>\n");

    return OK;
}

1;

__END__
$r->allow_ranges
允许在发送响应时使用字节范围。
$r->discard_request_body
指示 nginx 丢弃请求正文。
$r->header_in(field)
返回指定客户端请求头字段的值。
$r->header_only
确定是否应将整个响应或仅其标头发送到客户端。
$r->header_out(field, value)
为指定的响应头字段设置一个值。
$r->internal_redirect(uri)
执行内部重定向到指定的uri. 实际的重定向发生在 Perl 处理程序执行完成之后。
从版本 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])
将响应头发送给客户端。可选type参数设置“Content-Type”响应头字段的值。如果该值为空字符串,则不会发送“Content-Type”标头字段。
$r->status(code)
设置响应代码。
$r->sleep(milliseconds, handler)
设置指定的处理程序并在指定的时间内停止请求处理。与此同时,nginx 继续处理其他请求。经过指定时间后,nginx 将调用已安装的处理程序。请注意,处理程序函数应通过引用传递。为了在处理程序之间传递数据, $r->variable()应使用。例子:
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])
返回或设置指定变量的值。变量对于每个请求来说都是本地的。