Merge remote-tracking branch 'upstream/develop' into 4.8

# Conflicts:
#	system/HTTP/CLIRequest.php
#	tests/system/AutoReview/FrameworkCodeTest.php
#	tests/system/Cache/Handlers/MemcachedHandlerTest.php
#	tests/system/Cache/Handlers/PredisHandlerTest.php
#	tests/system/Cache/Handlers/RedisHandlerTest.php
#	utils/phpstan-baseline/empty.notAllowed.neon
#	utils/phpstan-baseline/loader.neon

Author: michalsn

.gitattributes

@@ -32,6 +32,7 @@ psalm-baseline.xml           export-ignore
 psalm.xml                    export-ignore
 psalm_autoload.php           export-ignore
 rector.php                   export-ignore
+AGENTS.md                    export-ignore
 
 # source user guide
 user_guide_src/ export-ignore

.github/copilot-instructions.md

@@ -0,0 +1,30 @@
+# Copilot Code Review Instructions
+
+Repository-wide conventions, the target-branch compatibility policy, coding
+standards, and FrankenPHP Worker Mode requirements are defined in the root
+`AGENTS.md`. Apply that policy in every review; this file covers review
+behavior only.
+
+## Review priorities
+
+Prioritize actionable findings involving:
+
+- incorrect behavior or an unhandled edge case;
+- backward compatibility;
+- security, input validation, and context-appropriate output escaping;
+- request-specific state leaking through globals, static properties, or
+  shared services, including under Worker Mode where one process serves
+  many requests;
+- differences between supported database drivers (MySQLi, PostgreSQL,
+  SQLite3, SQLSRV, OCI8);
+- missing regression tests, user-guide changes, changelog entries, or
+  upgrade instructions.
+
+## Review behavior
+
+- Determine the PR base branch and apply the compatibility policy from
+  `AGENTS.md`. If the base branch cannot be determined, assume `develop`
+  and state that assumption.
+- Do not report formatting-only issues already enforced by PHP-CS-Fixer.
+- Every finding should identify a concrete failure scenario and the
+  affected code.

.github/instructions/database.instructions.md

@@ -0,0 +1,19 @@
+---
+applyTo: "system/Database/**/*.php,tests/system/Database/**/*.php"
+---
+
+# Database layer
+
+- Consider all supported drivers: MySQLi, PostgreSQL, SQLite3, SQLSRV, and
+  OCI8.
+- Check identifier quoting, value binding, `NULL` behavior, transactions,
+  affected rows, return types, and platform-specific SQL.
+- Do not implement driver-independent behavior in only one driver.
+- When changing a base database class, inspect driver overrides and their
+  method signatures.
+- Keep driver-independent tests separate from tests that require a live
+  database.
+- Use the `DatabaseLive` PHPUnit group only when a real database connection is
+  required.
+- Prefer focused tests for the affected base class and drivers. Leave the full
+  multi-driver matrix to GitHub Actions.

.github/instructions/framework-core.instructions.md

@@ -0,0 +1,23 @@
+---
+applyTo: "system/**/*.php"
+---
+
+# Framework core
+
+- Assume public and protected symbols are extension points used by third-party
+  applications unless they are clearly marked internal.
+- Apply the target-branch compatibility policy from the root `AGENTS.md`
+  before changing any extension point.
+- Before changing a signature or behavior, inspect parent classes, implemented
+  interfaces, traits, service factories, configuration, and corresponding
+  tests.
+- Keep file paths, class names, and namespaces aligned under `CodeIgniter\`.
+- Preserve existing extension and dependency-injection points.
+- Consider long-running worker environments. Do not retain request-specific
+  state in static properties, globals, or shared services after a request
+  finishes.
+- Avoid introducing a framework-wide abstraction to solve a single local
+  problem.
+- On `develop`, keep exceptions and observable side effects compatible. On a
+  `4.*` target, change them only as an explicit, narrow, documented breaking
+  enhancement with a migration path.

.github/instructions/tests.instructions.md

@@ -0,0 +1,21 @@
+---
+applyTo: "tests/**/*.php"
+---
+
+# PHPUnit tests
+
+- Mirror the corresponding `system/` component and local test conventions
+  where practical.
+- Add the appropriate PHPUnit `Group` attribute described in
+  `tests/README.md`.
+- Prefer `assertSame()` and dedicated assertions over loose or generic
+  assertions.
+- Cover the regression or behavior through a public API where possible.
+  Avoid testing private implementation details.
+- Restore services, factories, environment variables, superglobals, handlers,
+  locale, time-related state, and other global state modified by a test.
+- Tests must not depend on execution order or state left by another test.
+- Do not replace a meaningful assertion with a weaker assertion to make a test
+  pass.
+- After changing behavior, run the smallest relevant test file or component.
+  Do not run the complete test suite by default.

.github/instructions/user-guide.instructions.md

@@ -0,0 +1,27 @@
+---
+applyTo: "user_guide_src/**/*.rst"
+---
+
+# User guide
+
+- Preserve the existing reStructuredText structure, terminology, directives,
+  anchors, and surrounding writing style.
+- Keep PHP examples compatible with PHP 8.2 and verify signatures and behavior
+  against the current framework code.
+- Distinguish new behavior from existing behavior and document defaults
+  precisely.
+- Determine the PR target branch before describing compatibility:
+  `develop` follows the patch-release policy, while `4.*` follows the
+  minor-release policy in the root `AGENTS.md`.
+- Behavior changes, enhancements, deprecations, and important bug fixes may
+  require a changelog entry.
+- Changes requiring users to modify code or configuration may require an
+  upgrading-guide entry.
+- For an intentional compatibility break targeting `4.*`, document the old
+  behavior, new behavior, affected users, reason for the change, and the
+  smallest migration in both the minor changelog and upgrading guide.
+- Keep code examples minimal but complete enough to run in a normal
+  CodeIgniter application.
+- Leave the complete Sphinx build and documentation validation to GitHub
+  Actions unless the task specifically requires local documentation
+  validation.

.github/instructions/worker-mode.instructions.md

@@ -0,0 +1,38 @@
+---
+applyTo: "system/Boot.php,system/CodeIgniter.php,system/Commands/Worker/**,system/Config/BaseService.php,system/Config/Factories.php,system/Config/Factory.php,system/Config/Services.php,system/Database/Config.php,system/Database/BaseConnection.php,system/Database/ConnectionInterface.php,system/Database/*/Connection.php,system/Events/Events.php,system/Session/**,system/Cache/**,system/HTTP/**,system/Filters/**,system/Router/**,system/Security/**,system/Debug/Toolbar.php,system/Debug/Toolbar/**,app/Config/WorkerMode.php,tests/system/Commands/Worker/**,user_guide_src/source/installation/worker_mode.rst"
+---
+
+# FrankenPHP Worker Mode
+
+Use `system/Commands/Worker/Views/frankenphp-worker.php.tpl` as the canonical
+Worker Mode entry point. `worker:install` publishes this template to
+`public/frankenphp-worker.php`.
+
+When changing bootstrap or request-lifecycle code, trace all three Worker Mode
+phases:
+
+1. One-time process bootstrap through `Boot::bootWorker()`.
+2. Per-request preparation: reconnect database and cache connections, reset
+   the `CodeIgniter` instance, and replace all request superglobals before
+   calling `$app->run()`.
+3. Post-request cleanup: close the session, clean up unfinished database
+   transactions, reset factories and non-persistent services, clean up event
+   listeners and performance logs, and reset the debug toolbar.
+
+- Preserve the phase ordering unless the change explicitly proves a different
+  order is safe.
+- Check every new mutable static property, singleton, shared service, event
+  listener, connection, handler, or global for cross-request state leakage.
+- Do not preserve a service across requests merely for performance. Persistent
+  services must be safe to reuse and must not retain request, response, user,
+  route, security token, locale, or error state.
+- Ensure exceptions and early exits cannot skip cleanup needed before the next
+  request.
+- For state-isolation fixes, prefer a regression test that exercises two
+  sequential requests or reset cycles in the same process and proves the
+  second request cannot observe the first request's state.
+- If the template contract changes, update focused assertions in
+  `tests/system/Commands/Worker/WorkerCommandsTest.php`.
+- If existing installations need the new generated entry point, update the
+  changelog and upgrading guide and instruct users to run
+  `php spark worker:install --force`.

.github/scripts/random-tests-config.txt

@@ -11,7 +11,7 @@
 API
 AutoReview
 Autoloader
-# Cache
+Cache
 CLI
 Commands
 Config
@@ -20,7 +20,7 @@ Cookie
 # DataConverter
 # Database
 # Debug
-# Email
+Email
 # Encryption
 # Entity
 Events

.github/workflows/deploy-apidocs.yml

@@ -30,13 +30,13 @@ jobs:
           git config --global user.name "${GITHUB_ACTOR}"
 
       - name: Checkout source
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           path: source
           persist-credentials: false
 
       - name: Checkout target
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           repository: codeigniter4/api
           token: ${{ secrets.ACCESS_TOKEN }}

.github/workflows/deploy-distributables.yml

@@ -16,7 +16,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0 # fetch all tags
           persist-credentials: false
@@ -50,13 +50,13 @@ jobs:
           git config --global user.name "${GITHUB_ACTOR}"
 
       - name: Checkout source
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           path: source
           persist-credentials: false
 
       - name: Checkout target
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           repository: codeigniter4/framework
           token: ${{ secrets.ACCESS_TOKEN }}
@@ -104,13 +104,13 @@ jobs:
           git config --global user.name "${GITHUB_ACTOR}"
 
       - name: Checkout source
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           path: source
           persist-credentials: false
 
       - name: Checkout target
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           repository: codeigniter4/appstarter
           token: ${{ secrets.ACCESS_TOKEN }}
@@ -158,21 +158,21 @@ jobs:
           git config --global user.name "${GITHUB_ACTOR}"
 
       - name: Checkout source
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           path: source
           persist-credentials: false
 
       - name: Checkout target
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           repository: codeigniter4/userguide
           token: ${{ secrets.ACCESS_TOKEN }}
           path: userguide
           persist-credentials: false
 
       - name: Setup Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: '3.12'