From 43cc6e286dffc7f31bfbb09a7496be16e96dee36 Mon Sep 17 00:00:00 2001
From: Traky <trakydeng@gmail.com>
Date: Fri, 25 Aug 2023 13:12:30 +0800
Subject: [PATCH 1/3] add register_custom_var.lua

---
 example/register_custom_var.lua | 42 +++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100644 example/register_custom_var.lua

diff --git a/example/register_custom_var.lua b/example/register_custom_var.lua
new file mode 100644
index 000000000000..399c07a3b56c
--- /dev/null
+++ b/example/register_custom_var.lua
@@ -0,0 +1,42 @@
+--
+-- Licensed to the Apache Software Foundation (ASF) under one or more
+-- contributor license agreements.  See the NOTICE file distributed with
+-- this work for additional information regarding copyright ownership.
+-- The ASF licenses this file to You under the Apache License, Version 2.0
+-- (the "License"); you may not use this file except in compliance with
+-- the License.  You may obtain a copy of the License at
+--
+--     http://www.apache.org/licenses/LICENSE-2.0
+--
+-- Unless required by applicable law or agreed to in writing, software
+-- distributed under the License is distributed on an "AS IS" BASIS,
+-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+-- See the License for the specific language governing permissions and
+-- limitations under the License.
+--
+local apisix = require "apisix"
+local core = require "apisix.core"
+
+local register_custom_var = function()
+    core.ctx.register_var("a6_route_labels", function(ctx)
+        local route = ctx.matched_route and ctx.matched_route.value
+        if route and route.labels then
+            return route.labels
+        end
+        return nil
+    end)
+end
+
+local old_http_init = apisix.http_init
+apisix.http_init = function(...)
+    register_custom_var()
+    ngx.log(ngx.EMERG, "my hook works in http")
+    old_http_init(...)
+end
+
+local old_stream_init = apisix.stream_init
+apisix.stream_init = function(...)
+    register_custom_var()
+    ngx.log(ngx.EMERG, "my hook works in stream")
+    old_stream_init(...)
+end

From 27e6845f163784e16843e53fc4cce9d98513cc44 Mon Sep 17 00:00:00 2001
From: Traky <trakydeng@gmail.com>
Date: Fri, 25 Aug 2023 13:22:06 +0800
Subject: [PATCH 2/3] add test

---
 t/cli/test_main.sh | 29 ++++++++++++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/t/cli/test_main.sh b/t/cli/test_main.sh
index 3b0cab766d59..30e53be31cf8 100755
--- a/t/cli/test_main.sh
+++ b/t/cli/test_main.sh
@@ -654,7 +654,7 @@ fi
 
 echo "passed: detect invalid extra_lua_path"
 
-# support hooking into APISIX methods
+# validate lua_module_hook
 echo '
 apisix:
     lua_module_hook: "example/my_hook"
@@ -668,6 +668,7 @@ fi
 
 echo "passed: bad lua_module_hook should be rejected"
 
+# support hooking into APISIX methods
 echo '
 apisix:
     proxy_mode: http&stream
@@ -697,6 +698,32 @@ fi
 
 echo "passed: hook can take effect"
 
+# register custom variable with the hook
+echo '
+apisix:
+    extra_lua_path: "\$prefix/example/?.lua"
+    lua_module_hook: "register_custom_var"
+' > conf/config.yaml
+
+rm logs/error.log
+make init
+make run
+
+sleep 0.5
+make stop
+
+if ! grep "my hook works in http" logs/error.log > /dev/null; then
+    echo "failed: hook can take effect"
+    exit 1
+fi
+
+if ! grep "my hook works in stream" logs/error.log > /dev/null; then
+    echo "failed: hook can take effect"
+    exit 1
+fi
+
+echo "passed: register custom variable with hook"
+
 # check the keepalive related parameter settings in the upstream
 git checkout conf/config.yaml
 

From f60eea71dfb6da541fd7b7a890ecf46b6c2f8cbb Mon Sep 17 00:00:00 2001
From: Traky <trakydeng@gmail.com>
Date: Fri, 25 Aug 2023 13:50:13 +0800
Subject: [PATCH 3/3] update doc

---
 docs/en/latest/plugin-develop.md | 27 +++++++++++++++++----------
 t/cli/test_main.sh               |  4 ++++
 2 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/docs/en/latest/plugin-develop.md b/docs/en/latest/plugin-develop.md
index 1b674303ecfe..de95184307f2 100644
--- a/docs/en/latest/plugin-develop.md
+++ b/docs/en/latest/plugin-develop.md
@@ -1,5 +1,5 @@
 ---
-title: Plugin Develop
+title: Develop Plugin
 ---
 
 <!--
@@ -71,8 +71,7 @@ apisix:
     lua_module_hook: "my_hook"
 ```
 
-The `example/my_hook.lua` will be loaded when APISIX starts, and you can use this hook to replace a method in APISIX.
-The example of [my_hook.lua](https://github.com/apache/apisix/blob/master/example/my_hook.lua) can be found under the `example` directory of this project.
+The `example/my_hook.lua` will be loaded when APISIX starts, and you can use this hook to replace a method in APISIX. The example of [my_hook.lua](https://github.com/apache/apisix/blob/master/example/my_hook.lua) can be found under the `example` directory of this project.
 
 ## check dependencies
 
@@ -488,25 +487,33 @@ curl -i -X GET "http://127.0.0.1:9090/v1/plugin/example-plugin/hello"
 
 ## register custom variable
 
-We can use variables in many places of APISIX. For example, customizing log format in http-logger, using it as the key of `limit-*` plugins. In some situations, the builtin variables are not enough. Therefore, APISIX allows developers to register their variables globally, and use them as normal builtin variables.
+You can also register your own variables and use them as built-in variables, for use cases such as customizing log format in logging plugins, or using built-in variables as keys in rate limiting plugins.
 
-For instance, let's register a variable called `a6_labels_zone` to fetch the value of the `zone` label in a route:
+For example, you can register a variable called `a6_route_labels` to obtain `labels` from a route:
 
-```
+```lua
 local core = require "apisix.core"
 
-core.ctx.register_var("a6_labels_zone", function(ctx)
+core.ctx.register_var("a6_route_labels", function(ctx)
     local route = ctx.matched_route and ctx.matched_route.value
     if route and route.labels then
-        return route.labels.zone
+      return route.labels
     end
     return nil
 end)
 ```
 
-After that, any get operation to `$a6_labels_zone` will call the registered getter to fetch the value.
+If you are developing a new plugin, the snippet could be added directly to your plugin source file.
+
+::: info
+
+If you are not doing development and would like to register a custom variable at runtime, you can run the snippet in serverless functions with the [`serverless`](plugins/serverless.md) plugins.
+
+:::
+
+Upon a successful registration, you can use the variable `$a6_route_labels` in configurations.
 
-Note that the custom variables can't be used in features that depend on the Nginx directive, like `access_log_format`.
+Note that the custom variables cannot be used in static configuration files, for example, to configure `access_log_format`.
 
 ## write test case
 
diff --git a/t/cli/test_main.sh b/t/cli/test_main.sh
index 30e53be31cf8..57e319090b19 100755
--- a/t/cli/test_main.sh
+++ b/t/cli/test_main.sh
@@ -701,8 +701,12 @@ echo "passed: hook can take effect"
 # register custom variable with the hook
 echo '
 apisix:
+    proxy_mode: http&stream
     extra_lua_path: "\$prefix/example/?.lua"
     lua_module_hook: "register_custom_var"
+    stream_proxy:
+        tcp:
+            - addr: 9100
 ' > conf/config.yaml
 
 rm logs/error.log