Opened 8 years ago

Closed 4 years ago

Last modified 4 years ago

#972 closed enhancement (wontfix)

Clarify $arg_name and $args in embedded variables documentation

Reported by: Neil Craig Owned by:
Priority: minor Milestone:
Component: documentation Version: 1.9.x
Keywords: Cc:
uname -a: Linux ip-10-13-149-100.eu-west-1.compute.internal 3.10.0-327.10.1.el7.x86_64 #1 SMP Tue Feb 16 17:03:50 UTC 2016 x86_64 x86_64 x86_64 GNU/Linux
nginx -V: nginx version: nginx/1.10.0 (BBC GTM) built with OpenSSL 1.1.0-pre4 (beta) 16 Mar 2016 TLS SNI support enabled configure arguments: --build='BBC GTM' --prefix=/usr/local/nginx --sbin-path=/usr/sbin/nginx --conf-path=/etc/nginx/current/nginx.conf --pid-path=/var/run/nginx.pid --error-log-path=/var/log/nginx/default-error.log --http-log-path=/var/log/nginx/default-access.log --lock-path=/var/run/nginx.lock --http-client-body-temp-path=/var/cache/nginx/client_temp --http-proxy-temp-path=/var/cache/nginx/proxy_temp --http-fastcgi-temp-path=/var/cache/nginx/fastcgi_temp --http-uwsgi-temp-path=/var/cache/nginx/uwsgi_temp --http-scgi-temp-path=/var/cache/nginx/scgi_temp --user=gtmdaemon --group=gtmdaemon --with-http_realip_module --with-http_v2_module --with-http_ssl_module --with-http_geoip_module --with-pcre-jit --with-ipv6 --with-file-aio --with-cc-opt='-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions -fstack-protector-strong --param=ssp-buffer-size=4 -grecord-gcc-switches -m64 -mtune=generic' --add-module=/tmp/tmpSlGmqp/BUILD/nginx-1.10.0/headers-more-nginx-module --add-module=/tmp/tmpSlGmqp/BUILD/nginx-1.10.0/naxsi/naxsi_src --add-module=/tmp/tmpSlGmqp/BUILD/nginx-1.10.0/nginx-module-vts --add-module=/tmp/tmpSlGmqp/BUILD/nginx-1.10.0/nginx-upstream-dynamic-servers --with-openssl=/tmp/tmpSlGmqp/BUILD/nginx-1.10.0/openssl-1.1.0-pre4

Description

Hi
I've just been documenting some of my project which is based on NGINX and did some tests to clarify the values of $args and $arg_name which I feel could be improved in docs: ​http://nginx.org/en/docs/http/ngx_http_core_module.html#variables

I'd suggest changing to the following:

$arg_name
The query string argument called 'name' in the request. For example, $arg_foo will have the value "bar" for a request which has a query string "?foo=bar&baz=1".

$args
The full query string received in the request (excluding the "?" character). For example, $args will have the value "foo=bar&baz=1" for a request which has a query string "?foo=bar&baz=1".

Cheers

Change History (4)

comment:1 by Maxim Dounin, 4 years ago

Resolution: wontfix
Status: newclosed

Suggested clarifications look unneeded and too verbose. If a reader don't know how HTTP requests look like, it should be explained elsewhere.

comment:2 by Eccenux@…, 4 years ago

Resolution: wontfix
Status: closedreopened

I respectfully disagree. It's not only the question of how HTTP request look like. It's a question how Nginx is interpreting it.

There should at least be a clarification if $args contains the question mark or not. Also would be nice to clarify that this can be modified. So:

$args
The full query string received in the request (excluding the "?" character). For example "foo=bar&baz=1". Note that $args can be modified, which will modify query string passed to a proxy.

Also note that $arg_name is a non-standard way of interpretation and I think that an example will clarify this. As you probably know in old PHP you used to have just $name for each variable from GET request. And you typically have an array. So this is Nginx specific.

comment:3 by Maxim Dounin, 4 years ago

Resolution: wontfix
Status: reopenedclosed

The $arg, also known as $query_string, represents query string as defined in RFC 3986, Section 3.4, "Query", and does not contain the question mark by definition. It certainly do not need further clarification.

The $arg_name follows application/x-www-form-urlencoded as defined by the HTML standard and not nginx-specific either. What may need clarification here is what happens if there is more than one argument with the same name, but the text suggested above does not try to clarify this.

Thank you for you opinion, but no.

comment:4 by wiedmann@…, 4 years ago

I would respectfully request that at least the term "query string" be included in the documentation. This bug report was very helpful to confirm that fact. "arguments in the request line" was not obvious to me.

Note: See TracTickets for help on using tickets.