[edit] Synopsis

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

[edit] 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.

[edit] Known Problems

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

1. If a Perl module performs protracted operation, (for example DNS lookups, database queries, etc), then the worker 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.
2. It's possible for Nginx to leak memory if you reload the configuration file (via 'kill -HUP <pid>').

Example:

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/>");
  $r->rflush;
 
  if (-f $r->filename or -d _) {
    $r->print($r->uri, " exists!\n");
  }
 
  return OK;
}
 
1;
__END__

[edit] Directives

[edit] perl

Directive establishes a function for the data location.

[edit] perl_modules

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.

[edit] perl_require

There can be multiple perl_require directives.

[edit] perl_set

Directive establishes the function of variable ???

[edit] Calling Perl from SSI

Instruction format is as follows:

<!--# perl sub="module::function" arg="parameter1" arg="parameter2"...
-->

[edit] Methods of request object $r

• $r->args - method returns the arguments of request.
• $r->discard_request_body - method tells nginx to discard the request body.
• $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(\&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->sleep(milliseconds, handler) - method sets the specified handler and stops processing the request at a given time. nginx will continue to process other requests in the meantime. After the specified timeout has expired, nginx will run the installed handler. Please note that you need to pass a reference to the function handler. To transfer data between processors you should use $r->variable(). Example of usage:

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->status(code) - sets the HTTP response code
• $r->unescape(text) - decodes the text, assigned in the form %XX.
• $r->uri - returns request URI.
• $r->variable(name[, value]) - the method returns or sets the value of the specified variable. Variables are local to each query.

[edit] References

Original Documentation