Merge branch 'dev'

README.md

@@ -14,6 +14,10 @@ You can use this library to make CodeIgniter4 able to define routing settings of
         - [Requirements](#requirements)
         - [Composer Install](#composer-install)
     - [Instructions](#instructions)
+        - [Production and Development Environment](#production-and-development-environment)
+            - [Configuration File](#configuration-file)
+            - [Generate Route Attribute Definition File](#generate-route-attribute-definition-file)
+            - [Update Route Attribute Definition File](#update-route-attribute-definition-file)
         - [Route](#route)
             - [options](#options)
             - [ignoreGroup](#ignoregroup)
@@ -26,9 +30,10 @@ You can use this library to make CodeIgniter4 able to define routing settings of
             - [only](#only)
             - [except](#except)
             - [placeholder](#placeholder)
-            - [options](#options)
-            - [ignoreGroup](#ignoregroup)
+            - [options](#options-1)
+            - [ignoreGroup](#ignoregroup-1)
         - [RouteGroup](#routegroup)
+        - [RouteEnvironment](#routeenvironment)
 
 <!-- /TOC -->
 
@@ -84,6 +89,12 @@ The upper command will make to changes on our project.
 
 1. `app/Config` will have a `RouteAttributes.php` configuration file, you can adjust the library's execution setting through this file. And it looks like this:
     ```php
+    <?php
+
+    namespace Config;
+
+    use CodeIgniter\Config\BaseConfig;
+
     class RouteAttributes extends BaseConfig
     {
 
@@ -94,7 +105,7 @@ The upper command will make to changes on our project.
         */
         public bool $enabled = true;
 
-        /**
+        /** 
         * autoscan namespaces
         *
         * @var array<string>
@@ -103,6 +114,22 @@ The upper command will make to changes on our project.
             "App\Controllers"
         ];
 
+        /**
+        * Generate production environment route definition file path
+        *
+        * @var string
+        */
+        public string $routeDefinitionFilePath = WRITEPATH . 'cache';
+
+        /**
+        * Whether to use pre-generated route definition files in production.
+        * Note that when this option is set to `true`, controller files will not be automatically
+        * scanned in production environment. You must use `route-attr:make` command to generate
+        * route definition files to improve performance in production environment.
+        *
+        * @var boolean
+        */
+        public bool $productionUseDefinitionFile = true;
     }
     ```
 2. Automatically write the library needed events into the endpoint of file `app/Config/Events.php`, the event will be used when CodeIgniter4 initializes, automatically registering routes. The command will write the contents in as below:
@@ -118,6 +145,35 @@ In short, this library is a [CodeIgniter4 Router](https://codeigniter.com/user_g
 
 By means of scanning the comments automatically inside the Controller, routes and methods will be connected, enables you to write routing rules straightforwardly, and maintain the relationship between Controllers and Routes in a convenient way.
 
+### Production and Development Environment
+
+When you are using this library in Development environment under CodeIgnitere4 framework, it will re-analyze all Controllers classes everytime when a request should occur, and meanwhile handle with the correspond Route Attribures. This strategy can bring maximum convenience to developing, changes of Route Attributes will take effect immediately. However, in production environment, this strategy will cause considerale performance loss. Therefore our library provides a cache-like method to lower the performance loss aiming at production environment.
+
+#### Configuration File
+
+You can find the two adjustable variables, `routeDefinitionFilePath` and `productionUseDefinitionFile`, in `app/Config/RouteAttributes.php`.
+
+You can use `routeDefinitionFilePath` to define storage location of your configuration file for production environment, it will be placed at `project_root/writable/cache` as default.
+
+You can change `productionUseDefinitionFile` as `true` or `false` to define whether to activate Route Attributes definition file in production environment or not to achieve the best performance. If it's `false`, then on every request of production environment, they will be re-scanned and Route Attributes inside Controllers will be handled.
+
+#### Generate Route Attribute Definition File
+
+You can generate your Route Attribute Definition File using the command below, to lower the performance loss: 
+
+```
+php spark route-attr:make
+```
+
+Upper mentioned command will generate a `RouteAttributesDefinition` file under the path defined in `routeDefinitionFilePath`.
+
+#### Update Route Attribute Definition File
+
+There are two ways to update the Route Attributes Definition File for your Production environment
+
+1. Run `php spark route-attr:make` again, new contents will directly cover the old ones.
+2. Delete `RouteAttributesDefinition` file, if the library couldn't find the file, it will scan and generate a Route Attribute Definition File automatically.
+
 ### Route
 
 You can register your routes like this:
@@ -383,3 +439,83 @@ $routes->group(
     }
 );
 ```
+### RouteEnvironment
+
+You can create special routes for specified environment, for instance, routes for development will be unavailable in production and staging environment. This requirement can be done through declaring `RouteEnvironment` in your class.
+
+```php
+<?php
+
+namespace App\Controllers;
+
+use monken\Ci4RouteAttributes\Route;
+
+#[RouteEnvironment(type: "development")]
+class EnvRoute extends BaseController
+{
+
+    #[Route(path:'dev/tool', methods:['cli'])]
+    public function devToolMethod()
+    {
+        return "tool msg";
+    }
+
+    #[Route(path:'dev/page', methods:['get'])]
+    public function devPageMethod()
+    {
+        return "page msg";
+    }
+
+```
+
+Upper setting equals to:
+
+```php
+$routes->environment('development', function ($routes) {
+    $routes->cli('dev/tool', 'App\Controllers\EnvRoute::devToolMethod');
+    $routes->get('dev/page', 'App\Controllers\EnvRoute::devPageMethod');
+});
+```
+
+If you need, `RouteEnvironment` can also work with `RouteGroup`:
+
+```php
+<?php
+
+namespace App\Controllers;
+
+use monken\Ci4RouteAttributes\Route;
+use monken\Ci4RouteAttributes\RouteGroup;
+
+#[RouteEnvironment(type: "development")]
+#[RouteGroup('/dev')]
+class EnvRoute extends BaseController
+{
+
+    #[Route(path:'tool', methods:['cli'])]
+    public function devToolMethod()
+    {
+        return "tool msg";
+    }
+
+    #[Route(path:'page', methods:['get'])]
+    public function devPageMethod()
+    {
+        return "page msg";
+    }
+
+```
+
+Upper setting equals to:
+
+```php
+$routes->environment('development', function ($routes) {
+    $routes->group(
+        '/dev',
+        function ($routes) {
+            $routes->cli('tool', 'App\Controllers\EnvRoute::devToolMethod');
+            $routes->get('page', 'App\Controllers\EnvRoute::devPageMethod');
+        }
+    );
+});
+```

README_zh-TW.md

@@ -12,6 +12,10 @@
         - [需求](#%E9%9C%80%E6%B1%82)
         - [Composer 安裝](#composer-%E5%AE%89%E8%A3%9D)
     - [使用說明](#%E4%BD%BF%E7%94%A8%E8%AA%AA%E6%98%8E)
+        - [正式環境與開發環境](#%E6%AD%A3%E5%BC%8F%E7%92%B0%E5%A2%83%E8%88%87%E9%96%8B%E7%99%BC%E7%92%B0%E5%A2%83)
+            - [組態設定檔](#%E7%B5%84%E6%85%8B%E8%A8%AD%E5%AE%9A%E6%AA%94)
+            - [產生路由屬性定義檔案](#%E7%94%A2%E7%94%9F%E8%B7%AF%E7%94%B1%E5%B1%AC%E6%80%A7%E5%AE%9A%E7%BE%A9%E6%AA%94%E6%A1%88)
+            - [更新路由屬性定義檔案](#%E6%9B%B4%E6%96%B0%E8%B7%AF%E7%94%B1%E5%B1%AC%E6%80%A7%E5%AE%9A%E7%BE%A9%E6%AA%94%E6%A1%88)
         - [Route](#route)
             - [options](#options)
             - [ignoreGroup](#ignoregroup)
@@ -27,6 +31,7 @@
             - [options](#options)
             - [ignoreGroup](#ignoregroup)
         - [RouteGroup](#routegroup)
+        - [RouteEnvironment](#routeenvironment)
 
 <!-- /TOC -->
 
@@ -82,6 +87,12 @@ php spark route-attr:init
 
 1. `app/Config` 將會出現 `RouteAttributes.php` 組態設定檔案，你能夠透過該檔案調整程式庫的執行設定。這個檔案長得會像這個樣子：
     ```php
+    <?php
+
+    namespace Config;
+
+    use CodeIgniter\Config\BaseConfig;
+
     class RouteAttributes extends BaseConfig
     {
 
@@ -92,7 +103,7 @@ php spark route-attr:init
         */
         public bool $enabled = true;
 
-        /**
+        /** 
         * autoscan namespaces
         *
         * @var array<string>
@@ -101,6 +112,22 @@ php spark route-attr:init
             "App\Controllers"
         ];
 
+        /**
+        * Generate production environment route definition file path
+        *
+        * @var string
+        */
+        public string $routeDefinitionFilePath = WRITEPATH . 'cache';
+
+        /**
+        * Whether to use pre-generated route definition files in production.
+        * Note that when this option is set to `true`, controller files will not be automatically
+        * scanned in production environment. You must use `route-attr:make` command to generate
+        * route definition files to improve performance in production environment.
+        *
+        * @var boolean
+        */
+        public bool $productionUseDefinitionFile = true;
     }
     ```
 2. 自動將程式庫所需的事件寫入 `app/Config/Events.php` 末端，這個事件用於在 CodeIgniter4 初始化時自動註冊路由。指令將自動寫入以下內容：
@@ -116,6 +143,35 @@ php spark route-attr:init
 
 它藉由自動掃描控制器中的註解，自動將路由與方法進行繫結，使你能夠直觀的撰寫路由規則，並便利地維護控制器與路由間的關係。
 
+### 正式環境與開發環境
+
+這個程式庫在 CodeIgniter4 處於 Development 環境時，將會在每一次請求發生時重新分析所有的 Controllers 類別，並處理相應 Route Attributes 。這種策略將會對開發帶來最高的便利，每一次 Route Attributes 發生改變都會即時地生效。但在正式環境時，這樣子的策略將會造成不小的效能損耗。所以本程式庫在針對 CodeIgniter4 處於 Production 環境時，提供了一種類似於快取的方式，使效能的耗損降到最低。
+
+#### 組態設定檔
+
+你可以在 `app/Config/RouteAttributes.php` 這支檔案找到 `routeDefinitionFilePath` 與 `productionUseDefinitionFile` 兩個可以調整的成員變數。
+
+你可以透過 `routeDefinitionFilePath` 定義正式環境下的路由定義檔案的存放位置，預設是放置在 `project_root/writable/cache` 下。
+
+你可以透過改變 `productionUseDefinitionFile` 為 `true` 或 `false` ，決定是否在正式環境中啟用路由定義檔案，以獲取最好的效能。若是這個屬性被設定為 `false` ，那麼在正式環境下的每一次請求，都將會重新掃描並處理 Controllers 中的 Route Attributes 。
+
+#### 產生路由屬性定義檔案
+
+你可以透過以下指令產生在 Production 環境下的路由屬性定義檔案，以減少效能的損耗：
+
+```
+php spark route-attr:make
+```
+
+上述指令將會在 `routeDefinitionFilePath` 所定義的路徑中，產生名為 `RouteAttributesDefinition` 的檔案。
+
+#### 更新路由屬性定義檔案
+
+有兩種方式可以更新 Production 環境下的路由屬性定義檔案。
+
+1. 重新執行 `php spark route-attr:make` 指令，新的內容將會直接覆蓋。
+2. 刪除 `RouteAttributesDefinition` 檔案，程式庫若是找不到該檔案，將會自動掃描並產生一份路由屬性定義檔案。
+
 ### Route
 
 你可以這麼註冊你的路由：
@@ -376,3 +432,84 @@ $routes->group(
     }
 );
 ```
+
+### RouteEnvironment
+
+你可以創造僅有在特定環境中可以使用的路由，比如：在開發模式能夠使用的路由，但在正式環境與測試環境無法使用。上述的需求你可以透過在類別上宣告 `RouteEnvironment` 做到。
+
+```php
+<?php
+
+namespace App\Controllers;
+
+use monken\Ci4RouteAttributes\Route;
+
+#[RouteEnvironment(type: "development")]
+class EnvRoute extends BaseController
+{
+
+    #[Route(path:'dev/tool', methods:['cli'])]
+    public function devToolMethod()
+    {
+        return "tool msg";
+    }
+
+    #[Route(path:'dev/page', methods:['get'])]
+    public function devPageMethod()
+    {
+        return "page msg";
+    }
+
+```
+
+上述設定將等同於：
+
+```php
+$routes->environment('development', function ($routes) {
+    $routes->cli('dev/tool', 'App\Controllers\EnvRoute::devToolMethod');
+    $routes->get('dev/page', 'App\Controllers\EnvRoute::devPageMethod');
+});
+```
+
+若你需要， `RouteEnvironment` 也能與 `RouteGroup` 一同工作：
+
+```php
+<?php
+
+namespace App\Controllers;
+
+use monken\Ci4RouteAttributes\Route;
+use monken\Ci4RouteAttributes\RouteGroup;
+
+#[RouteEnvironment(type: "development")]
+#[RouteGroup('/dev')]
+class EnvRoute extends BaseController
+{
+
+    #[Route(path:'tool', methods:['cli'])]
+    public function devToolMethod()
+    {
+        return "tool msg";
+    }
+
+    #[Route(path:'page', methods:['get'])]
+    public function devPageMethod()
+    {
+        return "page msg";
+    }
+
+```
+
+上述設定將等同於：
+
+```php
+$routes->environment('development', function ($routes) {
+    $routes->group(
+        '/dev',
+        function ($routes) {
+            $routes->cli('tool', 'App\Controllers\EnvRoute::devToolMethod');
+            $routes->get('page', 'App\Controllers\EnvRoute::devPageMethod');
+        }
+    );
+});
+```

composer.json

@@ -4,6 +4,7 @@
     "keywords": [
 		"codeigniter4",
 		"php8 attribute",
+        "attribute",
 		"router"
 	],
     "type": "library",
@@ -17,7 +18,8 @@
     "minimum-stability": "stable",
     "require": {
         "php" : "^8",
-        "haydenpierce/class-finder": "^0.4.3"
+        "haydenpierce/class-finder": "^0.4.3",
+        "codeigniter4/framework": "^4"
     },
     "autoload": {
 		"psr-4": {