{"id":31520,"date":"2019-06-12T06:18:38","date_gmt":"2019-06-11T21:18:38","guid":{"rendered":"https:\/\/jirak.net\/wp\/a-regular-expression-tester-for-nginx-and-nginx-plus\/"},"modified":"2019-06-12T06:34:24","modified_gmt":"2019-06-11T21:34:24","slug":"a-regular-expression-tester-for-nginx-and-nginx-plus","status":"publish","type":"post","link":"https:\/\/jirak.net\/wp\/a-regular-expression-tester-for-nginx-and-nginx-plus\/","title":{"rendered":"A Regular Expression Tester for NGINX and NGINX Plus"},"content":{"rendered":"

A Regular Expression Tester for NGINX and NGINX Plus
\n<\/p>\n

While working on a regular expression (regex) to use with NGINX, I got an idea for a way to easily test a regex from within an actual NGINX configuration. (The regex tester works just the same for NGINX Plus<\/a>, but for ease of reading I’ll refer to NGINX<\/em>.)<\/p>\n

Support for regular expressions is one of the powerful features of NGINX, but regexes can be complex and difficult to get right, especially if you don\u2019t work with them regularly. NGINX allows regexes in multiple parts of a configuration, for example locations, maps, rewrites, and server names. The tester described here is for regexes in locations and maps.<\/p>\n

There are other free online regex testers that are good for most regexes, but NGINX uses some non‑standard shortcuts optimized for web applications. For example, you don\u2019t have to escape the forward slash (\/) in a URI as you do in a standard regex. Also, when using a regex in a map, you specify what value to set based on a match. With other regex testers you might have to modify the regex or, in the case of a map, infer what value will be set. In addition, it is always good to be able to test a regex with the actual regex engine in the actual environment.<\/p>\n

Overview<\/h2>\n

This post assumes a basic understanding of NGINX and regular expressions. NGINX uses Perl Compatible Regular Expressions<\/a> (PCRE).<\/p>\n

Before we get into the details of the regex tester, let\u2019s first discuss how regexes can be used in NGINX locations and maps.<\/p>\n

Locations<\/h3>\n

NGINX regex locations are of the form:<\/p>\n

location regex<\/em> {\r\n    #...\r\n}<\/code><\/pre>\n
For example, a location<\/code><\/a> block with the following regex handles all PHP requests with a URI ending with myapp\/filename<\/em>.php<\/strong>, such as \/test\/myapp\/hello.php<\/strong> and \/myapp\/hello.php<\/strong>. The asterisk after the tilde (~*<\/code>) makes the match case insensitive.<\/p>\n
location ~* \/myapp\/.+.php$ {\r\n    #...\r\n}<\/code><\/pre>\n
NGINX and the regex tester support positional capture groups in location<\/code> blocks. In the following example, the first group captures everything before the PHP file name and the second captures the PHP filename:<\/p>\n
location ~* (.*\/myapp)\/(.+.php)$ {\r\n    #...\r\n}<\/code><\/pre>\n
For the URI \/myapp\/hello.php<\/strong>, the variable $1<\/code> is set to \/myapp<\/code> and $2<\/code> is set to hello.php<\/code>.<\/p>\n
NGINX also supports named capture groups (but note that the regex tester does not):<\/p>\n
location ~* (?<begin>.*myapp)\/(?<end>.+.php)$ {\r\n    #...\r\n}<\/code><\/pre>\n
In this case the variable $begin<\/code> is set to \/myapp\/<\/code> and $end<\/code> is set to hello.php<\/code>.<\/p>\n
Maps<\/h3>\n
NGINX maps that use regular expressions are of the form:<\/p>\n
map variable-from-request variable-to-set<\/em> {\r\n    regex1 value-to-set-if-match<\/em>;\r\n    regex2 value-to-set-if-match<\/em>;\r\n    #...\r\n    regexN value-to-set-if-match<\/em>;\r\n    default value-to-set-if-no-match<\/em>;\r\n}<\/code><\/pre>\n
For example, this map<\/code><\/a> block sets the variable $isphp<\/code> to 1<\/code> if the URI (as recorded in the $uri<\/code> variable) ends in .php<\/strong>, and 0<\/code> if it does not (the match is case sensitive):<\/p>\n
map $uri $isphp {\r\n    ~.php$ 1;\r\n    default 0;\r\n}<\/code><\/pre>\n
For maps, NGINX and the regex tester support both positional and named capture groups.<\/p>\n
For example, these maps both set the variable $fileext<\/code> to the value of the file extension, which is also captured as $1<\/code> in the first block and $ext<\/code> in the second:<\/p>\n
map $uri $fileext {\r\n    ~*.+.(.+)$  $1;\r\n    default      '';\r\n}<\/code><\/pre>\n
Or:<\/p>\n
map $uri $fileext {\r\n    ~*.+.(?.+)$  $ext;\r\n    default            '';\r\n}<\/code><\/pre>\n
The Regular Expression Tester<\/h2>\n
The regex tester is implemented in a Docker container with NGINX and NGINX Unit<\/a> installed. NGINX Unit serves two variations of a PHP page, one for regexes in location<\/code> blocks and the other for regexes in map<\/code> blocks. The two pages prompt the user for different inputs:<\/p>\n