feat(filtering): Add method/path filters, fix hook docs and .env guidance

Author: noplanalderson

CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-09-02
+
+### Added
+
+- Request filtering: `REQUEST_LOG_METHODS` (limit logged HTTP methods),
+  `REQUEST_LOG_INCLUDE_PATHS` (regex allow-list) and
+  `REQUEST_LOG_EXCLUDE_PATHS` (regex deny-list) so not every `GET /` ends up
+  in the log.
+
+### Fixed
+
+- Documentation: the array hook format in `hooks.php` never worked for
+  Composer namespaced classes (`CI_Hooks::_run_hook()` bypasses autoloaders
+  and `require_once`s the configured file path). The README, hook docblock and
+  sample now use the working **closure** registration format.
+- Documentation: added an explicit `.env` loading section — CI3 does not parse
+  `.env` files, so `REQUEST_LOG_*` must be exposed via vlucas/phpdotenv,
+  Apache `SetEnv`, or Nginx `fastcgi_param`.
+- Documentation: added note about custom Composer `vendor-dir`
+  (e.g. `application/third_party/vendor`) and pointing
+  `$config['composer_autoload']` at the exact autoload path.
+
 ## [1.0.1] - 2026-09-02
 
 ### Fixed
@@ -36,5 +58,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Sample CI3 application under `sample/` with a Home controller demonstrating
   JSON POST and multipart file upload endpoints.
 
+[1.1.0]: https://github.com/mrnaeem4/ci3-request-analysis/releases/tag/v1.1.0
 [1.0.1]: https://github.com/mrnaeem4/ci3-request-analysis/releases/tag/v1.0.1
 [1.0.0]: https://github.com/mrnaeem4/ci3-request-analysis/releases/tag/v1.0.0

README.md

@@ -37,6 +37,12 @@ rotation with gzip compression.
 composer require mrnaeem4/ci3-request-analysis
 ```
 
+> **Custom `vendor-dir`:** If your `composer.json` sets `"vendor-dir"`
+> (e.g. `application/third_party/vendor`), the package installs there. That is
+> fine — just point `$config['composer_autoload']` at that exact
+> `vendor/autoload.php` path. CodeIgniter's `TRUE` shortcut only looks at
+> `application/vendor/` and the project root.
+
 If you do not use Composer, add a PSR-4 autoloader mapping
 `MrNaeem\Ci3RequestAnalysis\` to the `src/` directory, or require the three
 classes manually:
@@ -60,21 +66,62 @@ $config['composer_autoload'] = TRUE; // or absolute path to vendor/autoload.php
 
 ### 2. Register the hook
 
+> **Important:** CI3's array hook format (`class`/`function`/`filename`/
+> `filepath`) cannot resolve Composer namespaced classes — `CI_Hooks::_run_hook()`
+> checks `class_exists($class, false)` (no autoload) and then `require_once`s
+> the `filepath`/`filename`, which fails for vendor files. Use a **closure**
+> instead (CI3 supports callables natively):
+
 In `application/config/hooks.php`:
 
 ```php
-$hook['post_controller_constructor'] = [
-    'class'    => 'MrNaeem\Ci3RequestAnalysis\Hooks\RequestLogHook',
-    'function' => 'before',
-    'filename' => '',
-    'filepath' => '',
-    'params'   => [],
-];
+$hook['post_controller_constructor'] = function () {
+    (new \MrNaeem\Ci3RequestAnalysis\Hooks\RequestLogHook())->before();
+};
+```
+
+### 3. Load the `.env` file
+
+CI3 does **not** parse a `.env` file by itself, and the config values are read
+with `getenv()`. Without loading the file, `REQUEST_LOG_ENABLED` is empty and
+the hook silently does nothing. Pick one:
+
+**Option A — vlucas/phpdotenv (recommended):**
+
+```bash
+composer require vlucas/phpdotenv
+```
+
+Load it in `index.php` (the front controller) **before** requiring
+`CodeIgniter.php`:
+
+```php
+require_once FCPATH . 'vendor/autoload.php';
+
+$dotenv = Dotenv\Dotenv::createUnsafeImmutable(FCPATH);
+$dotenv->safeLoad();
+```
+
+**Option B — Apache `SetEnv`:**
+
+```apache
+# .htaccess
+SetEnv REQUEST_LOG_ENABLED true
+SetEnv REQUEST_LOG_REDACT_FIELDS "password,nik,Cookie,Api-Key,no_telp"
+```
+
+**Option C — Nginx `fastcgi_param`:**
+
+```nginx
+location ~ \.php$ {
+    fastcgi_param REQUEST_LOG_ENABLED true;
+    # ...
+}
 ```
 
-### 3. Set environment variables
+### 4. Set environment variables
 
-Set in your web server environment or system environment:
+Values of the `.env` file (or server env):
 
 ```ini
 REQUEST_LOG_ENABLED          = true
@@ -85,6 +132,9 @@ REQUEST_LOG_MAX_BODY_SIZE    = 3145728
 REQUEST_LOG_WHITELIST_IPS    = "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,127.0.0.1"
 REQUEST_LOG_TRUNCATE_SUFFIX  = "... [truncated]"
 REQUEST_LOG_RETENTION_DAYS   = 30
+REQUEST_LOG_METHODS          = ""          # empty = log all; e.g. "POST,PUT,DELETE"
+REQUEST_LOG_INCLUDE_PATHS    = ""          # empty = log all; regex, e.g. "^/api/"
+REQUEST_LOG_EXCLUDE_PATHS    = ""          # regex, e.g. "^/assets/,^/health$"
 ```
 
 ### Config reference
@@ -99,6 +149,24 @@ REQUEST_LOG_RETENTION_DAYS   = 30
 | `REQUEST_LOG_WHITELIST_IPS` | RFC1918 + localhost | CIDR ranges to skip. |
 | `REQUEST_LOG_TRUNCATE_SUFFIX` | `... [truncated]` | Appended when the body is truncated. |
 | `REQUEST_LOG_RETENTION_DAYS` | `30` | Days of compressed logs kept before pruning. |
+| `REQUEST_LOG_METHODS` | `''` (all) | Comma-separated HTTP methods to log (e.g. `POST,PUT`). |
+| `REQUEST_LOG_INCLUDE_PATHS` | `''` (all) | Regex allow-list for request paths (comma-separated). |
+| `REQUEST_LOG_EXCLUDE_PATHS` | `''` (none) | Regex deny-list for request paths (comma-separated). |
+
+### Path & method filtering
+
+By default **every** request (including `GET /`) is logged. Restrict it:
+
+```ini
+# Only mutating requests, only under /api/, never static assets or health checks
+REQUEST_LOG_METHODS       = "POST,PUT,PATCH,DELETE"
+REQUEST_LOG_INCLUDE_PATHS = "^/api/"
+REQUEST_LOG_EXCLUDE_PATHS = "^/api/assets/,^/api/health$"
+```
+
+Patterns are regex matched against the request path (e.g. `/api/upload`).
+`includePaths` is evaluated first; a request must match at least one include
+pattern when that list is non-empty. `excludePaths` wins afterwards.
 
 ## Log payload
 
@@ -141,6 +209,7 @@ Each line in `analysis.log` is a JSON object (envelope + `log_data`):
 Request → CI3 Hook (post_controller_constructor)
   ├─ enabled? ──no──► done
   ├─ IP whitelisted? ──yes──► done
+  ├─ method/path filter passes? ──no──► done
   ├─ collect: headers, body, files, tenant, srcip...
   │    ├─ redact sensitive fields (headers + body)
   │    ├─ truncate body at max size
@@ -229,10 +298,9 @@ also rejects `*.log` / `*.gz` matches even if directory-level rules are ignored.
 
 ## Notes
 
-- The hook runs on every request once enabled. To log only specific
-  controllers, guard inside your controller or move the hook logic into a
-  base-controller `__construct()` call — see
-  `sample/application/controllers/Home.php` for a self-contained demo.
+- By default every request is logged (including `GET /`). Use
+  `REQUEST_LOG_METHODS` / `REQUEST_LOG_INCLUDE_PATHS` / `REQUEST_LOG_EXCLUDE_PATHS`
+  to narrow it down — see *Path & method filtering* above.
 - Binary file content is never stored; only metadata is captured.
 - Redaction applies to both request headers (e.g. `Cookie`) and the body.
 - `application/logs` should not be publicly accessible.

sample/application/config/hooks.php

@@ -5,17 +5,12 @@
 | -------------------------------------------------------------------------
 | Hooks
 | -------------------------------------------------------------------------
-| This file lets you define "hooks" to extend CI without hacking the core
-| files. Set $config['enable_hooks'] = TRUE in config.php first.
+| Set $config['enable_hooks'] = TRUE in config.php first.
 |
-| Attach the request analysis hook to post_controller_constructor so it runs
-| after the controller is instantiated (Composer autoload is already loaded).
+| Use a CLOSURE — CI3's array hook format (class/filename/filepath) cannot
+| resolve Composer namespaced classes. See README "Register the hook".
 */
 
-$hook['post_controller_constructor'] = [
-    'class'    => 'MrNaeem\Ci3RequestAnalysis\Hooks\RequestLogHook',
-    'function' => 'before',
-    'filename' => '',
-    'filepath' => '',
-    'params'   => [],
-];
+$hook['post_controller_constructor'] = function () {
+    (new \MrNaeem\Ci3RequestAnalysis\Hooks\RequestLogHook())->before();
+};

src/Config/RequestLog.php

@@ -20,6 +20,29 @@ class RequestLog
 
     public $retentionDays = 30;
 
+    /**
+     * HTTP methods to log (uppercase). Empty array = log all methods.
+     *
+     * @var array
+     */
+    public $logMethods = [];
+
+    /**
+     * Regex patterns (against the request path). When non-empty, only paths
+     * matching at least one pattern are logged.
+     *
+     * @var array
+     */
+    public $includePaths = [];
+
+    /**
+     * Regex patterns (against the request path). Matching paths are never
+     * logged. Applied after includePaths.
+     *
+     * @var array
+     */
+    public $excludePaths = [];
+
     public function __construct()
     {
         $this->enabled        = filter_var($this->env('REQUEST_LOG_ENABLED', $this->enabled), FILTER_VALIDATE_BOOLEAN);
@@ -38,6 +61,71 @@ public function __construct()
         if ($whitelist !== '') {
             $this->whitelistIps = $this->parseCsv($whitelist);
         }
+
+        $methods = (string) $this->env('REQUEST_LOG_METHODS', '');
+        if ($methods !== '') {
+            $this->logMethods = array_map('strtoupper', $this->parseCsv($methods));
+        }
+
+        $include = (string) $this->env('REQUEST_LOG_INCLUDE_PATHS', '');
+        if ($include !== '') {
+            $this->includePaths = $this->parseCsv($include);
+        }
+
+        $exclude = (string) $this->env('REQUEST_LOG_EXCLUDE_PATHS', '');
+        if ($exclude !== '') {
+            $this->excludePaths = $this->parseCsv($exclude);
+        }
+    }
+
+    /**
+     * Decide whether a request (method + path) passes the logging filters.
+     */
+    public function shouldLog(string $method, string $path): bool
+    {
+        $method = strtoupper($method);
+
+        $methods = array_map('strtoupper', (array) $this->logMethods);
+        if ($methods !== [] && ! in_array($method, $methods, true)) {
+            return false;
+        }
+
+        $include = (array) $this->includePaths;
+        if ($include !== [] && ! $this->matchesAny($path, $include)) {
+            return false;
+        }
+
+        $exclude = (array) $this->excludePaths;
+        if ($exclude !== [] && $this->matchesAny($path, $exclude)) {
+            return false;
+        }
+
+        return true;
+    }
+
+    protected function matchesAny(string $path, array $patterns): bool
+    {
+        foreach ($patterns as $pattern) {
+            $pattern = trim((string) $pattern);
+            if ($pattern === '') {
+                continue;
+            }
+
+            $result = @preg_match('~' . str_replace('~', '\~', $pattern) . '~', $path);
+
+            if ($result === 1) {
+                return true;
+            }
+
+            if ($result === false) {
+                // Invalid regex: fall back to a plain prefix match.
+                if (strpos($path, $pattern) === 0) {
+                    return true;
+                }
+            }
+        }
+
+        return false;
     }
 
     protected function env(string $key, $default)

src/Hooks/RequestLogHook.php

@@ -7,18 +7,16 @@
 
 /**
  * CI3 hook that captures request metadata and writes one JSONL line to the
- * CI3 logs directory. Attach via application/config/hooks.php:
+ * CI3 logs directory. Attach via application/config/hooks.php using a closure
+ * (CI3's array hook format cannot resolve Composer namespaced classes):
  *
- *   $hook['post_controller_constructor'] = [
- *       'class'    => 'MrNaeem\\Ci3RequestAnalysis\\Hooks\\RequestLogHook',
- *       'function' => 'before',
- *       'filename' => '',
- *       'filepath' => '',
- *       'params'   => [],
- *   ];
+ *   $hook['post_controller_constructor'] = function () {
+ *       (new \MrNaeem\Ci3RequestAnalysis\Hooks\RequestLogHook())->before();
+ *   };
  *
- * Requires $config['composer_autoload'] = TRUE in application/config/config.php
- * (or Composer loaded manually before the hook fires).
+ * Requires $config['composer_autoload'] pointing to your vendor/autoload.php
+ * in application/config/config.php. The request environment must expose the
+ * REQUEST_LOG_* variables (e.g. via vlucas/phpdotenv or SetEnv in Apache).
  */
 class RequestLogHook
 {
@@ -51,6 +49,12 @@ public function before()
                 return;
             }
 
+            $uri  = (string) ($CI->input->server('REQUEST_URI') ?? '/');
+            $path = parse_url($uri, PHP_URL_PATH) ?: '/';
+            if (! $this->config->shouldLog(strtoupper((string) $CI->input->method()), $path)) {
+                return;
+            }
+
             $data = $this->gather($CI, $ip);
             $log  = $this->service->collect($data);