Repository files navigation

array-var-nginx-module - Add support for array-typed variables to nginx config files

This module is not distributed with the Nginx source. See theinstallation instructions.

• Name
• Status
• Synopsis
• Description
• Directives
  • array_split
  • array_join
  • array_map
  • array_map_op
• Installation
  • Building as a dynamic module
• Compatibility
• Source Repository
• Getting involved
• Author
• Copyright & License
• See Also

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 tonginx.conf.

Under the hood, this module just "abuses" the nginx string values to hold binary pointersto C data structures (NGINX core'sngx_array_t struct on the C land).

The array type givesnginx.onf wonderful capabilities of handling value lists. Nowadays, however,you are highly recommended to use thengx_lua moduleso as to have the full scripting power provided by the Lua language in nginx.

Back to TOC

Back to TOC

syntax:array_split <separator> <subject> to=$target_variable

default:no

context:http, server, server if, location, location if

Splits the string value in thesubject argument with the separator string specified by theseparator argument. The result is an array-typed value saved to the nginx variable specified by theto=VAR option.

For example,

array_split","$arg_names to=$names;

will split the string values in the URI query argumentnames 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 outsidethe directives offered by this module. If you want to use the values in an array-typed variablein other contexts,you must use thearray_join directive to produce a normal string value.

Back to TOC

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 valuewith the separator specified by the first argument.

For example,

location /foo{    array_split','$arg_names to=$names;    array_join'+'$names;    echo$names;}

Then requestGET /foo?names=Bob,Marry,John will yield the response body

Bob+Marry+John

In the example above, we use thengx_echo module'secho directive to outputthe final result.

Back to TOC

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. Withinthe string template, you can use the special iterator variable$array_it to reference the currentarray 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 aroundeach element's string value. The modification is in-place in this case.

If you do not want in-place modifications, you can use theto=$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 whilethe$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 requestGET /foo?names=bob,marry,nomas will yield the response body

[bob]+[marry]+[nomas]

Back to TOC

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 thearray_map directive but maps the specified nginx configuration directive instead ofa string template to each element in the array-typed nginx variable specified. The resultof applying the specified configuration directive becomes the result of the mapping.

The nginx configuration directive being used as the iterator must be implemented byNginx Devel Kit (NDK)'s set_var submodule'sndk_set_var_value.For example, the followingset-misc-nginx-module directives can be invoked this way:

• set_quote_sql_str
• set_quote_pgsql_str
• set_quote_json_str
• set_unescape_uri
• set_escape_uri
• set_encode_base32
• set_decode_base32
• set_encode_base64
• set_decode_base64
• set_encode_hex
• set_decode_hex
• set_sha1
• set_md5

This is a higher-order operation where other nginx configuration directives can be usedas arguments for thismap_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 theset_quote_sql_strdirective provided by thengx_set_miscmodule 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 theto=$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 requestGET /foo?names=bob,marry,nomas will yield the response body

'bob'+'marry'+'nomas'

Pretty cool, huh?

Back to TOC

You're recommended to install this module (as well as the Nginx core and many other goodies) via theOpenResty bundle. Seethe 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 fromnginx.org, for example,the version 1.13.6 (seenginx 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.gzcd 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-modulemake -j2make install

Download the latest version of the release tarball of this module fromarray-var-nginx-module file list, and the latest tarball forngx_devel_kit from itsfile list.

Also, this module is included and enabled by default in theOpenResty bundle.

Back to TOC

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 yournginx.conf via theload_moduledirective, for example,

load_module /path/to/modules/ndk_http_module.so;  # assuming NDK is built as a dynamic module tooload_module /path/to/modules/ngx_http_array_var_module.so;

Back to TOC

The following versions of Nginx should work with this module:

• 1.13.x (last tested: 1.13.6)
• 1.12.x
• 1.11.x (last tested: 1.11.2)
• 1.10.x
• 1.9.x (last tested: 1.9.7)
• 1.8.x
• 1.7.x (last tested: 1.7.10)
• 1.6.x
• 1.5.x (last tested: 1.5.12)
• 1.4.x (last tested: 1.4.2)
• 1.2.x (last tested: 1.2.9)
• 1.1.x (last tested: 1.1.5)
• 1.0.x (last tested: 1.0.8)
• 0.9.x (last tested: 0.9.4)
• 0.8.x (last tested: 0.8.54)
• 0.7.x >= 0.7.44 (last tested: 0.7.68)

Earlier versions of Nginx like 0.6.x and 0.5.x willnot work.

If you find that any particular version of Nginx above 0.7.44 does notwork with this module, please consider reporting a bug.

Back to TOC

Available on github atopenresty/array-var-nginx-module.

Back to TOC

You'll be very welcomed to submit patches to the author or just ask fora commit bit to the source repository on GitHub.

Back to TOC

Yichun "agentzh" Zhang (章亦春) <agentzh@gmail.com>, CloudFlare Inc.

Back to TOC

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 withoutmodification, are permitted provided that the following conditions aremet:

• Redistributions of source code must retain the above copyrightnotice, this list of conditions and the following disclaimer.
• Redistributions in binary form must reproduce the above copyrightnotice, this list of conditions and the following disclaimer in thedocumentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "ASIS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITEDTO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR APARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHTHOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITEDTO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, ORPROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OFLIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDINGNEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THISSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Back to TOC

• NDK
• ngx_lua
• ngx_set_misc

Back to TOC