4.7.5 Ready code

.gitattributes

@@ -22,6 +22,7 @@ utils/                       export-ignore
 .php-cs-fixer.no-header.php  export-ignore
 .php-cs-fixer.tests.php      export-ignore
 .php-cs-fixer.user-guide.php export-ignore
+structarmed-baseline.php     export-ignore
 structarmed.php              export-ignore
 phpmetrics.json              export-ignore
 phpstan-baseline.php         export-ignore
@@ -32,6 +33,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/carson.yml

@@ -0,0 +1,125 @@
+# https://github.com/NexusPHP/carson/blob/1.x/SUBSCRIBERS.md
+
+version: 1
+subscribers:
+  - auto-labeler
+  - conflicts-notifier
+  - no-merge-commits
+  - no-response-closer
+  - pr-title-linter
+  - signed-commits
+  - template-enforcer
+  - welcome
+settings:
+  auto-labeler:
+    sync_labels: true
+    sync_exempt:
+      - enhancement
+    rules:
+      - label: '4.8' # @todo change value whenever the next minor version is changed
+        base_branch: ['^4\.8$']
+      - label: github_actions
+        files: ['.github/workflows/*']
+      - label: documentation
+        files:
+          all: ['user_guide_src/source/**']
+      - label: testing
+        files:
+          all: ['tests/**']
+      - label: bug
+        title: ['^fix(\([^)]*\))?: ']
+      - label: enhancement
+        title: ['^perf(\([^)]*\))?: ']
+      - label: refactor
+        title: ['^refactor(\([^)]*\))?: ']
+  conflicts-notifier:
+    label: stale
+    message: |-
+      :wave: Hi, @{{user}}!
+
+      We detected conflicts in your PR against the base branch :speak_no_evil:
+      You may want to sync :arrows_counterclockwise: your branch with upstream!
+
+      Ref: [Syncing Your Branch](https://github.com/codeigniter4/CodeIgniter4/blob/develop/contributing/workflow.md#updating-your-branch)
+  no-merge-commits:
+    name: 'Carson / no-merge-commits'
+    treat_merge_commits_as: failure
+    exempt_branches:
+      - head: '^develop$'
+        base: '^master$'
+      - head: '^4\.\d+$'
+        base: '^develop$'
+  no-response-closer:
+    rules:
+      - label: needs template
+        only: issues
+        days_until_close: 2
+        close_message: |-
+          Closing this issue: the description still does not follow the bug report template after {{days_until_close}} days.
+
+          Please open a new issue using the [bug report form](https://github.com/codeigniter4/CodeIgniter4/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=Bug%3A+). For feature requests or support questions, please use the [forums](https://forum.codeigniter.com/forum-30.html).
+      - label: waiting for info
+        days_until_close: 14
+        unlabel_on_response: true
+        close_message: |-
+          Closing this {{type}}: there has been no response for {{days_until_close}} days after more information was requested.
+
+          If you can provide the requested details, leave a comment and a maintainer can reopen it.
+  pr-title-linter:
+    name: 'Carson / pr-title-linter'
+    rules:
+      - pattern: '^(?:(?:\[\d+\.\d+\] )?(?:feat|fix|chore|docs|perf|refactor|style|test|config|revert)(?:\([\-.@:`a-zA-Z0-9]+\))?!?: \S.+\S|Prep for \d+\.\d+\.\d+ release|\d+\.\d+\.\d+ (?:Ready|Merge) code)$'
+        description: 'PR title must include the type (feat, fix, chore, docs, perf, refactor, style, test, config, revert) of the commit per Conventional Commits specification. See https://www.conventionalcommits.org/en/v1.0.0/ for the discussion.'
+        level: error
+  signed-commits:
+    name: 'Carson / signed-commits'
+    treat_unsigned_as: failure
+  template-enforcer:
+    label: needs template
+    exempt_roles: [admin, maintain, write, triage]
+    message: |-
+      Hi there, @{{user}}! :wave:
+
+      It looks like this {{type}} does not follow our template:
+
+      {{violations}}
+
+      Please update the description to follow the template. The `{{label}}` label will be removed automatically once it does.
+    issues:
+      rules:
+        - pattern: '### PHP Version[\s\S]*### CodeIgniter4 Version'
+          description: 'Use the [bug report form](https://github.com/codeigniter4/CodeIgniter4/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=Bug%3A+), which asks for your PHP and CodeIgniter4 versions. For a feature request or support question, please use the [forums](https://forum.codeigniter.com/forum-30.html).'
+    pull_requests:
+      rules:
+        - pattern: '\*\*Description\*\*'
+          description: 'Keep the **Description** heading from the [pull request template](https://github.com/codeigniter4/CodeIgniter4/blob/develop/.github/PULL_REQUEST_TEMPLATE.md) and explain what you have changed, and why.'
+        - pattern: '\*\*Checklist:?\*\*'
+          description: 'Keep the **Checklist** from the pull request template and tick the items that apply. See [what we expect in a pull request](https://github.com/codeigniter4/CodeIgniter4/blob/develop/contributing/pull_request.md).'
+        - pattern: 'Explain what you have changed, and why\.'
+          description: 'Replace the placeholder text under **Description** with your own explanation.'
+          mode: forbid
+  welcome:
+    first_time:
+      pull_request: |-
+        Hi there, @{{user}}! :wave:
+
+        Thank you for sending this PR!
+
+        We expect the following in all Pull Requests (PRs).
+        - PRs must be sent to the [appropriate branch](https://github.com/codeigniter4/CodeIgniter4/blob/develop/contributing/pull_request.md#branching)
+        - All git commits must be [GPG-signed](https://github.com/codeigniter4/CodeIgniter4/blob/develop/contributing/pull_request.md#signing)
+        - Must follow our [style guide](https://github.com/codeigniter4/CodeIgniter4/blob/develop/contributing/pull_request.md#php-style)
+        - Be [commented](https://github.com/codeigniter4/CodeIgniter4/blob/develop/contributing/pull_request.md#comments) in the PHP source file
+        - Be documented in the [user guide](https://github.com/codeigniter4/CodeIgniter4/blob/develop/contributing/pull_request.md#user-guide)
+        - Be [unit tested](https://github.com/codeigniter4/CodeIgniter4/blob/develop/contributing/pull_request.md#unit-testing)
+        - Pass all checks in GitHub Actions
+
+        > [!IMPORTANT]
+        > We expect all code changes or bug-fixes to be accompanied by one or more tests added to our test suite to prove the code works.
+
+        If pull requests do not comply with the above, they will likely be closed. Since we are a team of volunteers, we don't have any more time to work
+        on the framework than you do. Please make it as painless for your contributions to be included as possible.
+
+        See https://github.com/codeigniter4/CodeIgniter4/blob/develop/contributing/pull_request.md
+      issue: false
+    returning: false

.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`.