<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_perl_module"
        link="/en/docs/http/ngx_http_perl_module.html"
        lang="en"
        rev="7">

<section id="summary">

<para>
The <literal>ngx_http_perl_module</literal> module is used to implement
location and variable handlers in Perl and insert Perl calls into SSI.
</para>

<para>
This module is not built by default, it should be enabled with the
<literal>--with-http_perl_module</literal>
configuration parameter.
<note>
This module requires
<link url="https://www.perl.org/get.html">Perl</link> version 5.6.1 or higher.
The C compiler should be compatible with the one used to build Perl.
</note>
</para>

</section>


<section id="issues" name="Known Issues">

<para>
The module is experimental, caveat emptor applies.
</para>

<para>
In order for Perl to recompile the modified modules during
reconfiguration, it should be built with the
<literal>-Dusemultiplicity=yes</literal> or
<literal>-Dusethreads=yes</literal> parameters.
Also, to make Perl leak less memory at run time,
it should be built with the
<literal>-Dusemymalloc=no</literal> parameter.
To check the values of these parameters in an already built
Perl (preferred values are specified in the example), run:
<example>
$ perl -V:usemultiplicity -V:usemymalloc
usemultiplicity='define';
usemymalloc='n';
</example>
</para>

<para>
Note that after rebuilding Perl with the new
<literal>-Dusemultiplicity=yes</literal> or
<literal>-Dusethreads=yes</literal> parameters,
all binary Perl modules will have to be rebuilt as well —
they will just stop working with the new Perl.
</para>

<para>
There is a possibility that the main process and then worker processes will
grow in size after every reconfiguration.
If the main process grows to an unacceptable size, the
<link doc="../control.xml" id="upgrade">live upgrade</link>
procedure can be applied without changing the executable file.
</para>

<para>
While the Perl module is performing a long-running operation, such as
resolving a domain name, connecting to another server, or querying a database,
other requests assigned to the current worker process will not be processed.
It is thus recommended to perform only such operations
that have predictable and short execution time, such as
accessing the local file system.
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<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;
        }
    }
</example>
</para>

<para>
The <path>perl/lib/hello.pm</path> module:
<example>
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&lt;br/&gt;");

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

    return OK;
}

1;
__END__
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="perl">
<syntax><value>module</value>::<value>function</value>|'sub { ... }'</syntax>
<default/>
<context>location</context>
<context>limit_except</context>

<para>
Sets a Perl handler for the given location.
</para>

</directive>


<directive name="perl_modules">
<syntax><value>path</value></syntax>
<default/>
<context>http</context>

<para>
Sets an additional path for Perl modules.
</para>

</directive>


<directive name="perl_require">
<syntax><value>module</value></syntax>
<default/>
<context>http</context>

<para>
Defines the name of a module that will be loaded during each
reconfiguration.
Several <literal>perl_require</literal> directives can be present.
</para>

</directive>


<directive name="perl_set">
<syntax>
    <value>$variable</value>
    <value>module</value>::<value>function</value>|'sub { ... }'</syntax>
<default/>
<context>http</context>

<para>
Installs a Perl handler for the specified variable.
</para>

</directive>

</section>


<section id="ssi" name="Calling Perl from SSI">

<para>
An SSI command calling Perl has the following format:
<example>
&lt;!--# perl sub="<value>module</value>::<value>function</value>" arg="<value>parameter1</value>" arg="<value>parameter2</value>" ...
--&gt;
</example>
</para>

</section>


<section id="methods" name="The $r Request Object Methods">

<para>
<list type="tag">

<tag-name><literal>$r->args</literal></tag-name>
<tag-desc>
returns request arguments.
</tag-desc>

<tag-name><literal>$r->filename</literal></tag-name>
<tag-desc>
returns a filename corresponding to the request URI.
</tag-desc>

<tag-name>
    <literal>$r->has_request_body(<value>handler</value>)</literal>
</tag-name>
<tag-desc>
returns 0 if there is no body in a request.
If there is a body, the specified handler is set for the request
and 1 is returned.
After reading the request body, nginx will call the specified handler.
Note that the handler function should be passed by reference.
Example:
<example>
package hello;

use nginx;

sub handler {
    my $r = shift;

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

    if ($r->has_request_body(<emphasis>\&amp;post</emphasis>)) {
        return OK;
    }

    return HTTP_BAD_REQUEST;
}

sub <emphasis>post</emphasis> {
    my $r = shift;

    $r->send_http_header;

    $r->print("request_body: \"", $r->request_body, "\"&lt;br/&gt;");
    $r->print("request_body_file: \"", $r->request_body_file, "\"&lt;br/&gt;\n");

    return OK;
}

1;

__END__
</example>
</tag-desc>

<tag-name><literal>$r->allow_ranges</literal></tag-name>
<tag-desc>
enables the use of byte ranges when sending responses.
</tag-desc>

<tag-name><literal>$r->discard_request_body</literal></tag-name>
<tag-desc>
instructs nginx to discard the request body.
</tag-desc>

<tag-name><literal>$r->header_in(<value>field</value>)</literal></tag-name>
<tag-desc>
returns the value of the specified client request header field.
</tag-desc>

<tag-name><literal>$r->header_only</literal></tag-name>
<tag-desc>
determines whether the whole response or only its header should be sent to
the client.
</tag-desc>

<tag-name>
    <literal>$r->header_out(<value>field</value>,
    <value>value</value>)</literal>
</tag-name>
<tag-desc>
sets a value for the specified response header field.
</tag-desc>

<tag-name id="r_internal_redirect">
    <literal>$r->internal_redirect(<value>uri</value>)</literal>
</tag-name>
<tag-desc>
does an internal redirect to the specified <value>uri</value>.
An actual redirect happens after the Perl handler execution is completed.
<note>
Since version 1.17.2, the method accepts escaped URIs and
supports redirections to named locations.
</note>
</tag-desc>

<tag-name><literal>$r->log_error(<value>errno</value>,
<value>message</value>)</literal></tag-name>
<tag-desc>
writes the specified <value>message</value> into the
<link doc="../ngx_core_module.xml" id="error_log"/>.
If <value>errno</value> is non-zero, an error code and its description
will be appended to the message.
</tag-desc>

<tag-name><literal>$r->print(<value>text</value>, ...)</literal></tag-name>
<tag-desc>
passes data to a client.
</tag-desc>

<tag-name><literal>$r->request_body</literal></tag-name>
<tag-desc>
returns the client request body if it has not been
written to a temporary file.
To ensure that the client request body is in memory,
its size should be limited by
<link doc="ngx_http_core_module.xml" id="client_max_body_size"/>,
and a sufficient buffer size should be set using
<link doc="ngx_http_core_module.xml" id="client_body_buffer_size"/>.
</tag-desc>

<tag-name><literal>$r->request_body_file</literal></tag-name>
<tag-desc>
returns the name of the file with the client request body.
After the processing, the file should be removed.
To always write a request body to a file,
<link doc="ngx_http_core_module.xml" id="client_body_in_file_only"/>
should be enabled.
</tag-desc>

<tag-name><literal>$r->request_method</literal></tag-name>
<tag-desc>
returns the client request HTTP method.
</tag-desc>

<tag-name><literal>$r->remote_addr</literal></tag-name>
<tag-desc>
returns the client IP address.
</tag-desc>

<tag-name><literal>$r->flush</literal></tag-name>
<tag-desc>
immediately sends data to the client.
</tag-desc>

<tag-name>
    <literal>$r->sendfile(<value>name</value>[,
    <value>offset</value>[,
    <value>length</value>]])</literal>
</tag-name>
<tag-desc>
sends the specified file content to the client.
Optional parameters
specify the initial offset and length of the data to be transmitted.
The actual data transmission happens after the Perl handler
has completed.
</tag-desc>

<tag-name>
    <literal>$r->send_http_header([<value>type</value>])</literal>
</tag-name>
<tag-desc>
sends the response header to the client.
The optional <value>type</value> parameter sets the value of
the <header>Content-Type</header> response header field.
If the value is an empty string, the <header>Content-Type</header>
header field will not be sent.
</tag-desc>

<tag-name><literal>$r->status(<value>code</value>)</literal></tag-name>
<tag-desc>
sets a response code.
</tag-desc>

<tag-name>
    <literal>$r->sleep(<value>milliseconds</value>,
    <value>handler</value>)</literal>
</tag-name>
<tag-desc>
sets the specified handler
and stops request processing for the specified time.
In the meantime, nginx continues to process other requests.
After the specified time has elapsed, nginx will call the installed handler.
Note that the handler function should be passed by reference.
In order to pass data between handlers,
<literal>$r->variable()</literal> should be used.
Example:
<example>
package hello;

use nginx;

sub handler {
    my $r = shift;

    $r->discard_request_body;
    $r->variable("var", "OK");
    $r->sleep(1000, <emphasis>\&amp;next</emphasis>);

    return OK;
}

sub <emphasis>next</emphasis> {
    my $r = shift;

    $r->send_http_header;
    $r->print($r->variable("var"));

    return OK;
}

1;

__END__
</example>
</tag-desc>

<tag-name><literal>$r->unescape(<value>text</value>)</literal></tag-name>
<tag-desc>
decodes a text encoded in the “%XX” form.
</tag-desc>

<tag-name><literal>$r->uri</literal></tag-name>
<tag-desc>
returns a request URI.
</tag-desc>

<tag-name>
    <literal>$r->variable(<value>name</value>[,
    <value>value</value>])</literal>
</tag-name>
<tag-desc>
returns or sets the value of the specified variable.
Variables are local to each request.
</tag-desc>

</list>
</para>

</section>

</module>