模块 ngx_http_perl_module

已知问题 配置示例 指令      perl      perl_modules      perl_require      perl_set 从SSI调用Perl $r 请求对象方法

模块 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 模块 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处理程序。

为Perl模块设置额外路径。

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

为指定的变量安装 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("请求体: \"", $r->request_body, "\"<br/>");
    $r->print("请求体文件: \"", $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])

返回或设置指定变量的值。变量对每个请求都是局部的。