array-var-nginx-module - Add support for array-typed variables to nginx config files
This module is not distributed with the Nginx source. See the installation instructions.
This module is production ready.
location /foo {
array_split ',' $arg_files to=$array;
# use the set_quote_sql_str directive in the ngx_set_misc
# module to map to each element in the array $array:
array_map_op set_quote_sql_str $array;
array_map "name = $array_it" $array;
array_join ' or ' $array to=$sql_condition;
# well, we could feed it to ngx_drizzle to talk to MySQL, for example ;)
echo "select * from files where $sql_condition";
}This module provides array typed nginx variables to nginx.conf.
Under the hood, this module just "abuses" the nginx string values to hold binary pointers
to C data structures (NGINX core's ngx_array_t struct on the C land).
The array type gives nginx.onf wonderful capabilities of handling value lists. Nowadays, however,
you are highly recommended to use the ngx_lua module
so as to have the full scripting power provided by the Lua language in nginx.
syntax: array_split <separator> <subject> to=$target_variable
default: no
context: http, server, server if, location, location if
Splits the string value in the subject argument with the separator string specified by the
separator argument. The result is an array-typed value saved to the nginx variable specified by the to=VAR option.
For example,
array_split "," $arg_names to=$names;will split the string values in the URI query argument names into an array-typed value saved to the custom nginx variable
$names.
This directive creates an array-typed variable. Array-typed variables cannot be used outside the directives offered by this module. If you want to use the values in an array-typed variable in other contexts, you must use the array_join directive to produce a normal string value.
syntax: array_split <separator> $array_var
default: no
context: http, server, server if, location, location if
Joins the elements in the array-typed nginx variable ($array_var) into a single string value
with the separator specified by the first argument.
For example,
location /foo {
array_split ',' $arg_names to=$names;
array_join '+' $names;
echo $names;
}Then request GET /foo?names=Bob,Marry,John will yield the response body
Bob+Marry+JohnIn the example above, we use the ngx_echo module's echo directive to output the final result.
syntax: array_map <template> $array_var
syntax: array_map <template> $array_var to=$new_array_var
default: no
context: http, server, server if, location, location if
Maps the string template to each element in the array-typed nginx variable specified. Within
the string template, you can use the special iterator variable $array_it to reference the current
array element in the array being mapped.
For example,
array_map "[$array_it]" $names;will change each element in the array variable $names by putting the square brackets around
each element's string value. The modification is in-place in this case.
If you do not want in-place modifications, you can use the to=$var option to specify a new nginx variable to hold the results. For instance,
array_map "[$array_it]" $names to=$new_names;where the results are saved into another (array-typed) nginx variable named $new_names while
the $names variable keeps intact.
Below is a complete example for this:
location /foo {
array_split ',' $arg_names to=$names;
array_map '[$array_it]' $names;
array_join '+' $names;
echo "$names";
}Then request GET /foo?names=bob,marry,nomas will yield the response body
[bob]+[marry]+[nomas]syntax: array_map_op <directive> $array_var
syntax: array_map_op <directive> $array_var to=$new_array_var
default: no
context: http, server, server if, location, location if
Similar to the array_map directive but maps the specified nginx configuration directive instead of a string template to each element in the array-typed nginx variable specified. The result of applying the specified configuration directive becomes the result of the mapping.
The nginx configuration directive being used as the iterator must be implemented by Nginx Devel Kit (NDK)'s set_var submodule's ndk_set_var_value.
For example, the following set-misc-nginx-module directives can be invoked this way:
This is a higher-order operation where other nginx configuration directives can be used
as arguments for this map_array_op directive.
Consider the following example,
array_map_op set_quote_sql_str $names;This line changes each element in the array-typed nginx variable $names by applying the
set_quote_sql_str
directive provided by the ngx_set_misc
module one by one. The result is that each element in the array $names has been escaped as SQL string literal values.
You can also specify the to=$var option if you do not want in-place modifications of the input arrays. For instance,
array_map_op set_quote_sql_str $names to=$quoted_names;will save the escaped elements into a new (array-typed) nginx variable named $quoted_names with $names intact.
The following is a relatively complete example:
location /foo {
array_split ',' $arg_names to=$names;
array_map_op set_quote_sql_str $names;
array_join '+' $names to=$res;
echo $res;
}Then request GET /foo?names=bob,marry,nomas will yield the response body
'bob'+'marry'+'nomas'Pretty cool, huh?
You're recommended to install this module (as well as the Nginx core and many other goodies) via the OpenResty bundle. See the detailed instructions for downloading and installing OpenResty into your system. This is the easiest and most safe way to set things up.
Alternatively, you can install this module manually with the Nginx source:
Grab the nginx source code from nginx.org, for example, the version 1.13.6 (see nginx compatibility), and then build the source with this module:
wget 'http://nginx.org/download/nginx-1.13.6.tar.gz'
tar -xzvf nginx-1.13.6.tar.gz
cd nginx-1.13.6/
# Here we assume you would install you nginx under /opt/nginx/.
./configure --prefix=/opt/nginx \
--add-module=/path/to/ngx_devel_kit \
--add-module=/path/to/array-var-nginx-module
make -j2
make installDownload the latest version of the release tarball of this module from array-var-nginx-module file list, and the latest tarball for ngx_devel_kit from its file list.
Also, this module is included and enabled by default in the OpenResty bundle.
Starting from NGINX 1.9.11, you can also compile this module as a dynamic module, by using the --add-dynamic-module=PATH option instead of --add-module=PATH on the
./configure command line above. And then you can explicitly load the module in your nginx.conf via the load_module
directive, for example,
load_module /path/to/modules/ndk_http_module.so; # assuming NDK is built as a dynamic module too
load_module /path/to/modules/ngx_http_array_var_module.so;The following versions of Nginx should work with this module:
Earlier versions of Nginx like 0.6.x and 0.5.x will not work.
If you find that any particular version of Nginx above 0.7.44 does not work with this module, please consider reporting a bug.
Available on github at openresty/array-var-nginx-module.
You'll be very welcomed to submit patches to the author or just ask for a commit bit to the source repository on GitHub.
Yichun "agentzh" Zhang (章亦春) <agentzh@gmail.com>, CloudFlare Inc.
Copyright (c) 2009-2016, Yichun Zhang (agentzh) <agentzh@gmail.com>, CloudFlare Inc.
This module is licensed under the terms of the BSD license.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.