{"id":13635851,"url":"https://github.com/openresty/array-var-nginx-module","last_synced_at":"2025-04-19T04:31:28.615Z","repository":{"id":806206,"uuid":"510988","full_name":"openresty/array-var-nginx-module","owner":"openresty","description":"Add support for array-typed variables to nginx config files","archived":false,"fork":false,"pushed_at":"2023-11-23T11:35:09.000Z","size":128,"stargazers_count":64,"open_issues_count":2,"forks_count":19,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-02-13T09:12:50.251Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://openresty.org","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openresty.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2010-02-10T09:39:00.000Z","updated_at":"2024-08-02T00:03:26.882Z","dependencies_parsed_at":"2024-08-02T00:03:25.311Z","dependency_job_id":"9733b305-8802-45c1-a47d-4e67db9f4773","html_url":"https://github.com/openresty/array-var-nginx-module","commit_stats":{"total_commits":63,"total_committers":4,"mean_commits":15.75,"dds":0.07936507936507942,"last_synced_commit":"32188f86599b47f7cd34340e5a2985bd9d550bf8"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Farray-var-nginx-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Farray-var-nginx-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Farray-var-nginx-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openresty%2Farray-var-nginx-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openresty","download_url":"https://codeload.github.com/openresty/array-var-nginx-module/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249606349,"owners_count":21298851,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T00:00:53.110Z","updated_at":"2025-04-19T04:31:28.358Z","avatar_url":"https://github.com/openresty.png","language":"C","funding_links":[],"categories":["Modules","Third Modules","Third Party Modules","Lua and OpenResty ecosystem"],"sub_categories":["C Modules"],"readme":"Name\n====\n\narray-var-nginx-module - Add support for array-typed variables to nginx config files\n\n*This module is not distributed with the Nginx source.* See the\ninstallation instructions.\n\nTable of Contents\n=================\n\n* [Name](#name)\n* [Status](#status)\n* [Synopsis](#synopsis)\n* [Description](#description)\n* [Directives](#directives)\n    * [array_split](#array_split)\n    * [array_join](#array_join)\n    * [array_map](#array_map)\n    * [array_map_op](#array_map_op)\n* [Installation](#installation)\n    * [Building as a dynamic module](#building-as-a-dynamic-module)\n* [Compatibility](#compatibility)\n* [Source Repository](#source-repository)\n* [Getting involved](#getting-involved)\n* [Author](#author)\n* [Copyright \u0026 License](#copyright--license)\n* [See Also](#see-also)\n\nStatus\n======\n\nThis module is production ready.\n\nSynopsis\n========\n\n```nginx\nlocation /foo {\n    array_split ',' $arg_files to=$array;\n\n    # use the set_quote_sql_str directive in the ngx_set_misc\n    # module to map to each element in the array $array:\n    array_map_op set_quote_sql_str $array;\n\n    array_map \"name = $array_it\" $array;\n\n    array_join ' or ' $array to=$sql_condition;\n\n    # well, we could feed it to ngx_drizzle to talk to MySQL, for example ;)\n    echo \"select * from files where $sql_condition\";\n}\n```\n\nDescription\n===========\n\nThis module provides array typed nginx variables to `nginx.conf`.\n\nUnder the hood, this module just \"abuses\" the nginx string values to hold binary pointers\nto C data structures (NGINX core's `ngx_array_t` struct on the C land).\n\nThe array type gives `nginx.onf` wonderful capabilities of handling value lists. Nowadays, however,\nyou are highly recommended to use the [ngx_lua](https://github.com/openresty/lua-nginx-module) module\nso as to have the full scripting power provided by the Lua language in nginx.\n\n[Back to TOC](#table-of-contents)\n\nDirectives\n==========\n\n[Back to TOC](#table-of-contents)\n\narray_split\n-----------\n**syntax:** *array_split \u0026lt;separator\u0026gt; \u0026lt;subject\u0026gt; to=$target_variable*\n\n**default:** *no*\n\n**context:** *http, server, server if, location, location if*\n\nSplits the string value in the `subject` argument with the separator string specified by the\n`separator` argument. The result is an array-typed value saved to the nginx variable specified by the `to=VAR` option.\n\nFor example,\n\n```nginx\narray_split \",\" $arg_names to=$names;\n```\n\nwill split the string values in the URI query argument `names` into an array-typed value saved to the custom nginx variable\n`$names`.\n\nThis directive creates an array-typed variable. Array-typed variables cannot be used outside\nthe directives offered by this module. If you want to use the values in an array-typed variable\nin other contexts,\nyou must use the [array_join](#array_join) directive to produce a normal string value.\n\n[Back to TOC](#table-of-contents)\n\narray_join\n----------\n**syntax:** *array_split \u0026lt;separator\u0026gt; $array_var*\n\n**default:** *no*\n\n**context:** *http, server, server if, location, location if*\n\nJoins the elements in the array-typed nginx variable (`$array_var`) into a single string value\nwith the separator specified by the first argument.\n\nFor example,\n\n```nginx\nlocation /foo {\n    array_split ',' $arg_names to=$names;\n    array_join '+' $names;\n    echo $names;\n}\n```\n\nThen request `GET /foo?names=Bob,Marry,John` will yield the response body\n\n```\nBob+Marry+John\n```\n\nIn the example above, we use the [ngx_echo](https://github.com/openresty/echo-nginx-module) module's [echo](https://github.com/openresty/echo-nginx-module#echo) directive to output\nthe final result.\n\n[Back to TOC](#table-of-contents)\n\narray_map\n---------\n**syntax:** *array_map \u0026lt;template\u0026gt; $array_var*\n\n**syntax:** *array_map \u0026lt;template\u0026gt; $array_var to=$new_array_var*\n\n**default:** *no*\n\n**context:** *http, server, server if, location, location if*\n\nMaps the string template to each element in the array-typed nginx variable specified. Within\nthe string template, you can use the special iterator variable `$array_it` to reference the current\narray element in the array being mapped.\n\nFor example,\n\n```nginx\narray_map \"[$array_it]\" $names;\n```\n\nwill change each element in the array variable `$names` by putting the square brackets around\neach element's string value. The modification is in-place in this case.\n\nIf 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,\n\n```nginx\narray_map \"[$array_it]\" $names to=$new_names;\n```\n\nwhere the results are saved into another (array-typed) nginx variable named `$new_names` while\nthe `$names` variable keeps intact.\n\nBelow is a complete example for this:\n\n```nginx\nlocation /foo {\n    array_split ',' $arg_names to=$names;\n    array_map '[$array_it]' $names;\n    array_join '+' $names;\n    echo \"$names\";\n}\n```\n\nThen request `GET /foo?names=bob,marry,nomas` will yield the response body\n\n```\n[bob]+[marry]+[nomas]\n```\n\n[Back to TOC](#table-of-contents)\n\narray_map_op\n------------\n**syntax:** *array_map_op \u0026lt;directive\u0026gt; $array_var*\n\n**syntax:** *array_map_op \u0026lt;directive\u0026gt; $array_var to=$new_array_var*\n\n**default:** *no*\n\n**context:** *http, server, server if, location, location if*\n\nSimilar to the [array_map](#array_map) directive but maps the specified nginx configuration directive instead of\na string template to each element in the array-typed nginx variable specified. The result\nof applying the specified configuration directive becomes the result of the mapping.\n\nThe nginx configuration directive being used as the iterator must be implemented by [Nginx Devel Kit](https://github.com/simpl/ngx_devel_kit) (NDK)'s set_var submodule's `ndk_set_var_value`.\nFor example, the following [set-misc-nginx-module](http://github.com/openresty/set-misc-nginx-module) directives can be invoked this way:\n\n* [set_quote_sql_str](http://github.com/openresty/set-misc-nginx-module#set_quote_sql_str)\n* [set_quote_pgsql_str](http://github.com/openresty/set-misc-nginx-module#set_quote_pgsql_str)\n* [set_quote_json_str](http://github.com/openresty/set-misc-nginx-module#set_quote_json_str)\n* [set_unescape_uri](http://github.com/openresty/set-misc-nginx-module#set_unescape_uri)\n* [set_escape_uri](http://github.com/openresty/set-misc-nginx-module#set_escape_uri)\n* [set_encode_base32](http://github.com/openresty/set-misc-nginx-module#set_encode_base32)\n* [set_decode_base32](http://github.com/openresty/set-misc-nginx-module#set_decode_base32)\n* [set_encode_base64](http://github.com/openresty/set-misc-nginx-module#set_encode_base64)\n* [set_decode_base64](http://github.com/openresty/set-misc-nginx-module#set_decode_base64)\n* [set_encode_hex](http://github.com/openresty/set-misc-nginx-module#set_encode_base64)\n* [set_decode_hex](http://github.com/openresty/set-misc-nginx-module#set_decode_base64)\n* [set_sha1](http://github.com/openresty/set-misc-nginx-module#set_encode_base64)\n* [set_md5](http://github.com/openresty/set-misc-nginx-module#set_decode_base64)\n\nThis is a higher-order operation where other nginx configuration directives can be used\nas arguments for this `map_array_op` directive.\n\nConsider the following example,\n\n```nginx\narray_map_op set_quote_sql_str $names;\n```\n\nThis line changes each element in the array-typed nginx variable `$names` by applying the\n[set_quote_sql_str](https://github.com/openresty/set-misc-nginx-module#set_quote_sql_str)\ndirective provided by the [ngx_set_misc](https://github.com/openresty/set-misc-nginx-module)\nmodule one by one. The result is that each element in the array `$names` has been escaped as SQL string literal values.\n\nYou can also specify the `to=$var` option if you do not want in-place modifications of the input arrays. For instance,\n\n```nginx\narray_map_op set_quote_sql_str $names to=$quoted_names;\n```\n\nwill save the escaped elements into a new (array-typed) nginx variable named `$quoted_names` with `$names` intact.\n\nThe following is a relatively complete example:\n\n```nginx\nlocation /foo {\n    array_split ',' $arg_names to=$names;\n    array_map_op set_quote_sql_str $names;\n    array_join '+' $names to=$res;\n    echo $res;\n}\n```\n\nThen request `GET /foo?names=bob,marry,nomas` will yield the response body\n\n```\n'bob'+'marry'+'nomas'\n```\n\nPretty cool, huh?\n\n[Back to TOC](#table-of-contents)\n\nInstallation\n============\n\nYou're recommended to install this module (as well as the Nginx core and many other goodies) via the [OpenResty bundle](http://openresty.org). See [the detailed instructions](http://openresty.org/#Installation) for downloading and installing OpenResty into your system. This is the easiest and most safe way to set things up.\n\nAlternatively, you can install this module manually with the Nginx source:\n\nGrab the nginx source code from [nginx.org](http://nginx.org/), for example,\nthe version 1.13.6 (see [nginx compatibility](#compatibility)), and then build the source with this module:\n\n```bash\nwget 'http://nginx.org/download/nginx-1.13.6.tar.gz'\ntar -xzvf nginx-1.13.6.tar.gz\ncd nginx-1.13.6/\n\n# Here we assume you would install you nginx under /opt/nginx/.\n./configure --prefix=/opt/nginx \\\n  --add-module=/path/to/ngx_devel_kit \\\n  --add-module=/path/to/array-var-nginx-module\n\nmake -j2\nmake install\n```\n\nDownload the latest version of the release tarball of this module from [array-var-nginx-module file list](https://github.com/openresty/array-var-nginx-module/tags), and the latest tarball for [ngx_devel_kit](https://github.com/simplresty/ngx_devel_kit) from its [file list](https://github.com/simplresty/ngx_devel_kit/tags).\n\nAlso, this module is included and enabled by default in the [OpenResty bundle](http://openresty.org).\n\n[Back to TOC](#table-of-contents)\n\nBuilding as a dynamic module\n----------------------------\n\nStarting 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\n`./configure` command line above. And then you can explicitly load the module in your `nginx.conf` via the [load_module](http://nginx.org/en/docs/ngx_core_module.html#load_module)\ndirective, for example,\n\n```nginx\nload_module /path/to/modules/ndk_http_module.so;  # assuming NDK is built as a dynamic module too\nload_module /path/to/modules/ngx_http_array_var_module.so;\n```\n\n[Back to TOC](#table-of-contents)\n\nCompatibility\n==============\n\nThe following versions of Nginx should work with this module:\n\n* **1.13.x** (last tested: 1.13.6)\n* **1.12.x**\n* **1.11.x** (last tested: 1.11.2)\n* **1.10.x**\n* **1.9.x** (last tested: 1.9.7)\n* **1.8.x**\n* **1.7.x** (last tested: 1.7.10)\n* **1.6.x**\n* **1.5.x** (last tested: 1.5.12)\n* **1.4.x** (last tested: 1.4.2)\n* **1.2.x** (last tested: 1.2.9)\n* **1.1.x** (last tested: 1.1.5)\n* **1.0.x** (last tested: 1.0.8)\n* **0.9.x** (last tested: 0.9.4)\n* **0.8.x** (last tested: 0.8.54)\n* **0.7.x \u003e= 0.7.44** (last tested: 0.7.68)\n\nEarlier versions of Nginx like 0.6.x and 0.5.x will *not* work.\n\nIf you find that any particular version of Nginx above 0.7.44 does not\nwork with this module, please consider reporting a bug.\n\n[Back to TOC](#table-of-contents)\n\nSource Repository\n=================\n\nAvailable on github at [openresty/array-var-nginx-module](https://github.com/openresty/array-var-nginx-module).\n\n[Back to TOC](#table-of-contents)\n\nGetting involved\n================\n\nYou'll be very welcomed to submit patches to the author or just ask for\na commit bit to the source repository on GitHub.\n\n[Back to TOC](#table-of-contents)\n\nAuthor\n======\n\nYichun \"agentzh\" Zhang (章亦春) \u0026lt;agentzh@gmail.com\u0026gt;, CloudFlare Inc.\n\n[Back to TOC](#table-of-contents)\n\nCopyright \u0026 License\n===================\n\nCopyright (c) 2009-2016, Yichun Zhang (agentzh) \u0026lt;agentzh@gmail.com\u0026gt;, CloudFlare Inc.\n\nThis module is licensed under the terms of the BSD license.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are\nmet:\n\n*   Redistributions of source code must retain the above copyright\nnotice, this list of conditions and the following disclaimer.\n*   Redistributions in binary form must reproduce the above copyright\nnotice, this list of conditions and the following disclaimer in the\ndocumentation and/or other materials provided with the distribution.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS\nIS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED\nTO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A\nPARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT\nHOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,\nSPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED\nTO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR\nPROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF\nLIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING\nNEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\nSOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n[Back to TOC](#table-of-contents)\n\nSee Also\n========\n\n* [NDK](https://github.com/simpl/ngx_devel_kit)\n* [ngx_lua](https://github.com/openresty/lua-nginx-module)\n* [ngx_set_misc](https://github.com/openresty/set-misc-nginx-module)\n\n[Back to TOC](#table-of-contents)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenresty%2Farray-var-nginx-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenresty%2Farray-var-nginx-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenresty%2Farray-var-nginx-module/lists"}