Модуль http_ssi

Фильтр, обрабатывающий команды SSI (Server Side Includes) в проходящих через него ответах.

Пример конфигурации

location / {
    ssi on;
#    ...
}

Директивы

ssi

Синтаксис:

ssi on | off;

Умолчание:

ssi off;

Контекст:

http, server, location, if в location

Разрешает или запрещает обработку команд SSI в ответах.

ssi_last_modified

Синтаксис:

ssi_last_modified on | off;

Умолчание:

ssi_last_modified off;

Контекст:

http, server, location

Позволяет сохранить поле заголовка «Last-Modified» исходного ответа во время обработки SSI для лучшего кэширования ответов.

По умолчанию поле заголовка удаляется, так как содержимое ответа изменяется во время обработки и может содержать динамически созданные элементы или части, которые изменились независимо от исходного ответа.

ssi_min_file_chunk

Синтаксис:

ssi_min_file_chunk размер;

Умолчание:

ssi_min_file_chunk 1k;

Контекст:

http, server, location

Задает минимальный размер частей ответа, хранящихся на диске, начиная с которого имеет смысл посылать их с помощью sendfile.

ssi_silent_errors

Синтаксис:

ssi_silent_errors on | off;

Умолчание:

ssi_silent_errors off;

Контекст:

http, server, location

Разрешает не выводить строку «[an error occurred while processing the directive]», если во время обработки SSI произошла ошибка.

ssi_types

Синтаксис:

ssi_types mime-тип …;

Умолчание:

ssi_types text/html;

Контекст:

http, server, location

Разрешает обработку команд SSI в ответах с указанными MIME-типами в дополнение к «text/html». Специальное значение «*» соответствует любому MIME-типу.

ssi_value_length

Синтаксис:

ssi_value_length длина;

Умолчание:

ssi_value_length 256;

Контекст:

http, server, location

Задает максимальную длину значений параметров в SSI-командах.

Команды SSI

Общий формат команд SSI такой:

<!--# команда параметр1=значение1 параметр2=значение2 ... -->

Поддерживаются следующие команды:

block

Описывает блок, который можно использовать как заглушку в команде include. Внутри блока могут быть другие команды SSI. Параметр команды:

name

имя блока.

Пример:

<!--# block name="one" -->
заглушка
<!--# endblock -->

config

Задает некоторые параметры, используемые при обработке SSI, а именно:

errmsg

строка, выводящаяся при ошибке во время обработки SSI. По умолчанию выводится такая строка:

[an error occurred while processing the directive]

timefmt

строка формата, передаваемая функции strftime() для вывода даты и времени. По умолчанию используется такой формат:

«%A, %d-%b-%Y %H:%M:%S %Z»

Для вывода времени в секундах подходит формат «%s».

echo

Выводит значение переменной. Параметры команды:

var

имя переменной.

encoding

способ кодирования. Возможны три значения — none, url и entity.
По умолчанию используется entity.

default

нестандартный параметр, задающий строку, которая выводится, если переменная не определена.
По умолчанию выводится строка «(none)».

Команда

<!--# echo var="name" default="нет" -->

заменяет такую последовательность команд:

<!--# if expr="$name" --><!--# echo var="name" --><!--#
     else -->нет<!--# endif -->

if

Выполняет условное включение. Поддерживаются следующие команды:

<!--# if expr="..." -->
...
<!--# elif expr="..." -->
...
<!--# else -->
...
<!--# endif -->

На данный момент поддерживается только один уровень вложенности. Параметр команды:

expr

выражение. В выражении может быть:

• проверка существования переменной:

<!--# if expr="$name" -->

• сравнение переменной с текстом:

<!--# if expr="$name = text" -->
<!--# if expr="$name != text" -->

• сравнение переменной с регулярным выражением:

<!--# if expr="$name = /text/" -->
<!--# if expr="$name != /text/" -->

Если в text встречаются переменные, то производится подстановка их значений. В регулярном выражении можно задать позиционные и именованные выделения, а затем использовать их через переменные, например:

<!--# if expr="$name = /(.+)@(?P<domain>.+)/" -->
  <!--# echo var="1" -->
  <!--# echo var="domain" -->
<!--# endif -->

include

Включает в ответ результат другого запроса. Параметры команды:

file

задает включаемый файл, например:

<!--# include file="footer.html" -->

virtual

задает включаемый запрос, например:

<!--# include virtual="/remote/body.php?argument=value" -->

Несколько запросов, указанных на одной странице и обрабатываемых проксируемыми или FastCGI/uwsgi/SCGI/gRPC-серверами, работают параллельно. Если нужна последовательная обработка, следует воспользоваться параметром wait.

stub

нестандартный параметр, задающий имя блока, содержимое которого будет выведено, если тело ответа на включаемый запрос пустое или если при исполнении запроса произошла ошибка, например:

<!--# block name="one" -->&nbsp;<!--# endblock -->
<!--# include virtual="/remote/body.php?argument=value" stub="one" -->

Содержимое замещающего блока обрабатывается в контексте включаемого запроса.

wait

нестандартный параметр, указывающий, нужно ли ждать полного исполнения данного запроса, прежде чем продолжать выполнение SSI, например:

<!--# include virtual="/remote/body.php?argument=value" wait="yes" -->

set

нестандартный параметр, указывающий, что удачный результат выполнения запроса нужно записать в заданную переменную, например:

<!--# include virtual="/remote/body.php?argument=value" set="one" -->

Максимальный размер ответа задается директивой subrequest_output_buffer_size:

location /remote/ {
    subrequest_output_buffer_size 64k;
#    ...
}

set

Присваивает значение переменной. Параметры команды:

var

имя переменной.

value

значение переменной. Если в присваиваемом значении есть переменные, то производится подстановка их значений.

Встроенные переменные

$date_local

текущее время в локальной временной зоне. Формат задается командой config с параметром timefmt.

$date_gmt

текущее время в GMT. Формат задается командой config с параметром timefmt.