http_perl_module makes it possible to execute Perl directly within Nginx and call Perl via SSI.

Building Module at Compile-time

Unless built at compile-time, the module is not available. The default is to not build this module. If you want to enable this module, is necessary to specify --with-http_perl_module when running configure.

Your system must have Perl 5.6.1 or above.

Known Problems

This module is experimental; therefore anything is possible and bugs are likely.

1. It's possible for Nginx to leak memory if you reload the configuration file (via 'kill -HUP <pid>').

2. If a Perl module performs protracted operation, (for example DNS lookups, database queries, etc), then the process that is running the Perl script is completely tied up for the duration of script. Therefore embedded Perl scripts should be extremely careful to limit themselves to short, predictable operations.
3. Nginx may laugh at your Perl code and hit on your girlfriend.

Nginx 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:

   1 package hello;
   2 use nginx;
   3 
   4 sub handler {
   5     my $r = shift;
   6     $r->send_http_header("text/html");
   7     return OK if $r->header_only;
   8 
   9     $r->print("hello!\n<br/>");
  10     $r->rflush;
  11 
  12     if (-f $r->filename or -d _) {
  13        $r->print($r->uri, " exists!\n");
  14     }
  15 
  16     return OK;
  17 }
  18 
  19 1;
  20 __END__

Directives

• perl

• perl_modules

• perl_require

• perl_set

perl

syntax: perl module::function | 'sub {...}'

default: no

context: location

Directive establishes a function for the data location.

perl_modules

syntax: perl_modules path

default: no

context: http

Directive assigns additional path for Perl modules. Since version 0.6.7 this path is relative to directory of nginx configuration file nginx.conf, but not to nginx prefix directory.

perl_require

syntax: perl_require module

default: no

context: http

There can be multiple perl_require directives.

perl_set

syntax: perl_set module::function | 'sub {...}'

default: no

context: http

Directive establishes the function of variable ???

Call Perl from SSI

Instruction format is as follows: <!- # perl sub="module::function" arg="parameter1" arg="parameter2"... >

Methods of request object $r:

• $r->args - method returns the arguments of request.

• $r->filename - method returns the name of file, which corresponds to URI request.

• $r->has_request_body(function) - method returns 0, if there is no request body. But if the request body exists, then the passed function is established and 1 returned. At the end of the body processing, nginx will call the established processor. Example usage:

package hello;

use nginx;

sub handler {
    my $r = shift;

    if ($r->request_method ne "POST") {
        return DECLINED;
    }

    if ($r->has_request_body(hello::post)) {
        return OK;
    }

    return 400;
}

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->header_in(header) - retrieve an HTTP request header.

• $r->header_only - true if we only need to return a response header.

• $r->header_out(header, value) - set a response header.

• $r->internal_redirect(uri) - method makes internal redirect to the indicated uri. Redirect occurs only after the completion of Perl script.

• $r->print(args, ...) - sends data to client.

• $r->request_body - method returns the request body of client when the body is not recorded into the temporary file.

  • So that the body of the demand of client is guaranteed to remain in memory, it is necessary to limit its size with the aid of client_max_body_size and to assign sufficient size for the buffer using client_body_buffer_size.

• $r->request_body_file — method returns the name of the file, in which is stored the body of the demand of client. The file must be removed on the completion of work. So that the body of the request would always be written to the file, it is necessary to indicate client_body_in_file_only on.

• $r->request_method — method returns the HTTP method of the request.

• $r->remote_addr - method returns IP address of client.

• $r->rflush - method immediately transmits data to client.

• $r->sendfile(file [, displacement [, length ] ]) - transfers to client contents of the file indicated. The optional parameters indicate initial offset and length of transmitted data. Strictly the transmission of data occurs only after the completion of the perl script.

• $r->send_http_header(type) - adds header to response. The optional parameter "type" establishes the value of line "Content-Type" in the title of answer.

• $r->unescape(text) - decodes the text, assigned in the form %XX.

• $r->uri - returns request URI.

References

Original Documentation