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/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 モジュール::関数\|'sub { ... }';`
デフォルト	—
コンテキスト	`location`, `limit_except`

指定されたロケーションの Perl ハンドラを設定します。

構文	`perl_modules パス;`
デフォルト	—
コンテキスト	`http`

Perl モジュールの追加パスを設定します。

構文	`perl_require モジュール;`
デフォルト	—
コンテキスト	`http`

再構成ごとにロードされるモジュールの名前を定義します。複数の perl_require ディレクティブを指定できます。

構文	`perl_set $変数モジュール::関数\|'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(ハンドラ)

リクエストに本文がない場合は 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(フィールド)

指定されたクライアントリクエストヘッダーフィールドの値を返します。

$r->header_only

クライアントにレスポンス全体を送信するか、ヘッダーのみを送信するかを決定します。

$r->header_out(フィールド, 値)

指定されたレスポンスヘッダーフィールドの値を設定します。

$r->internal_redirect(uri)

指定された uri に内部リダイレクトを実行します。実際のリダイレクトは、Perl ハンドラの thực thi が完了した後に発生します。

バージョン 1.17.2 以降、このメソッドはエスケープされた URI を受け入れ、名前付きロケーションへのリダイレクトをサポートしています。

$r->log_error(エラー番号, メッセージ)

指定された メッセージ をerror_logに書き込みます。エラー番号 が 0 以外の場合、エラーコードとその説明がメッセージに追加されます。

$r->print(テキスト, ...)

クライアントにデータを渡します。

$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(名前[, オフセット[, 長さ]])

指定されたファイルの内容をクライアントに送信します。オプションのパラメータは、送信されるデータの初期オフセットと長さを指定します。実際のデータ送信は、Perl ハンドラが完了した後に発生します。

$r->send_http_header([タイプ])

レスポンスヘッダーをクライアントに送信します。オプションの タイプ パラメータは、「Content-Type」レスポンスヘッダーフィールドの値を設定します。値が空の文字列の場合、「Content-Type」ヘッダーフィールドは送信されません。

$r->status(コード)

レスポンスコードを設定します。

$r->sleep(ミリ秒, ハンドラ)

指定されたハンドラを設定し、指定された時間だけリクエスト処理を停止します。その間、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(テキスト)

「%XX」形式でエンコードされたテキストをデコードします。

$r->uri

リクエスト URI を返します。

$r->variable(名前[, 値])

指定された変数の値を返したり設定したりします。変数は各リクエストに対してローカルです。