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, but for ease of reading I’ll refer to NGINX.)
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’t 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.
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’t 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.
[Editor – The tester is no longer under active development. We regret that we cannot satisfy change requests, and our ability to ability to help with troubleshooting is limited. To reach other members of the NGINX open source community, post a question on the NGINX mailing list.]
Overview
This post assumes a basic understanding of NGINX and regular expressions. NGINX uses Perl Compatible Regular Expressions (PCRE).
Before we get into the details of the regex tester, let’s first discuss how regexes can be used in NGINX locations and maps.
Locations
NGINX regex locations are of the form:
location regex {
#...
}For example, a location block with the following regex handles all PHP requests with a URI ending with myapp/filename.php, such as /test/myapp/hello.php and /myapp/hello.php. The asterisk after the tilde (~*) makes the match case insensitive.
location ~* /myapp/.+\.php$ {
#...
}NGINX and the regex tester support positional capture groups in location blocks. In the following example, the first group captures everything before the PHP file name and the second captures the PHP filename:
location ~* (.*/myapp)/(.+\.php)$ {
#...
}For the URI /myapp/hello.php, the variable $1 is set to /myapp and $2 is set to hello.php.
NGINX also supports named capture groups (but note that the regex tester does not):
location ~* (?<begin>.*myapp)/(?<end>.+\.php)$ {
#...
}In this case the variable $begin is set to /myapp and $end is set to hello.php.
Maps
NGINX maps that use regular expressions are of the form:
map variable-from-request variable-to-set {
regex1 value-to-set-if-match;
regex2 value-to-set-if-match;
#...
regexN value-to-set-if-match;
default value-to-set-if-no-match;
}For example, this map block sets the variable $isphp to 1 if the URI (as recorded in the $uri variable) ends in .php, and 0 if it does not (the match is case sensitive):
map $uri $isphp {
~\.php$ 1;
default 0;
}For maps, NGINX and the regex tester support both positional and named capture groups.
For example, these maps both set the variable $fileext to the value of the file extension, which is also captured as $1 in the first block and $ext in the second:
map $uri $fileext {
~*.+\.(.+)$ $1;
default '';
}Or:
map $uri $fileext {
~*.+\.(?<ext>.+)$ $ext;
default '';
}The Regular Expression Tester
The regex tester is implemented in a Docker container with NGINX and NGINX Unit installed. NGINX Unit serves two variations of a PHP page, one for regexes in location blocks and the other for regexes in map blocks. The two pages prompt the user for different inputs:
-
Location page:
- The regex
- Case sensitivity
- The URI
-
Map page:
- The regex
- Case sensitivity
- The value to test (the value of the variable that is the first parameter to the
mapdirective) - The value to set in the variable specified as the second parameter to the
mapdirective
After providing the information, the user clicks the Test button. The tester generates the necessary NGINX configuration file, the configuration is reloaded, and a request is sent to test the regex. The results are then displayed and indicate whether a match was found. If so, on the location page the values of the capture groups are dispalyed, and on the map page the value set by the map is reported.
Location Page Example
This example shows the results of a case‑insensitive test of the regex (.*myapp)/(.+\.php)$ against the URI /myapp/hello.php:
Map Page Example
This example shows the results of a case‑insensitive test of the regex .+\.(?<ext>.*)$ against the value /myapp/hello.php, with the named capture group $ext as the value to set:
Conclusion
You can see that the NGINX configuration is quite short and simple. The hard work is done by the PHP page that generates the necessary NGINX configuration file based on the values entered by the user, reloads NGINX, sends a request to NGINX, and displays the results.
You can try out the regex tester for yourself: all the code is available at our GitHub repo (https://github.com/nginxinc/NGINX-Demos/tree/master/nginx-regex-tester).
To make it easy to get the regex tester up and running, all the necessary files are included. To build the Docker image and build the container, simply run:
$ docker-compose up -dThen point your browser to http://Docker-host/regextester.php.
I hope you find tester helpful when using regular expressions and that it gives you a glimpse of some of the power, flexibility, and simplicity of NGINX.
To try out the regex tester with NGINX Plus, start your free 30-day trial today or contact us to discuss your use cases.
[Editor – The tester is no longer under active development. We regret that we cannot satisfy change requests, and our ability to ability to help with troubleshooting is limited. To reach other members of the NGINX open source community, post a question on the NGINX mailing list.]
