Merge branch 'master' of https://github.com/windwalker-io/framework

Author: asika32764

.env.docker

@@ -0,0 +1,13 @@
+# .env.docker – Copy to .env to override default ports in docker-compose.yml
+
+# MySQL host port (default: 3306)
+# MYSQL_PORT=3307
+
+# PostgreSQL host port (default: 5432)
+# PGSQL_PORT=5433
+
+# Redis host port (default: 6379)
+# REDIS_PORT=6380
+
+# Memcached host port (default: 11211)
+# MEMCACHED_PORT=11212

.gitattributes

@@ -1,11 +1,15 @@
-/tmp export-ignore
+w/tmp export-ignore
 /.gitattributes export-ignore
 /.gitignore export-ignore
 /.travis.yml export-ignore
 /.github export-ignore
 /package.json export-ignore
 /phpunit.travis.xml export-ignore
 /phpunit.xml.dist export-ignore
+/docker export-ignore
+/docker-compose.yml export-ignore
+/docker-compose.override.yml.dist export-ignore
+/.env.docker export-ignore
 /packages/*/test export-ignore
 /packages/*/.gitattributes export-ignore
 /packages/*/.gitignore export-ignore

.github/copilot-instructions.md

@@ -0,0 +1,10 @@
+# Copilot Instructions
+
+## General Guidelines
+
+See `/AGENTS.md` for general guidelines on how to use Copilot effectively.
+
+## Others
+
+- Global Code Style: See `/.github/instructions/cs.instructions.md` for advanced code style instructions.
+- Testing Code Style: See `/.github/instructions/test.instructions.md` for testing-specific code style instructions.

.github/instructions/cs.instructions.md

@@ -0,0 +1,15 @@
+# Advanced Code Style Instructions
+
+## Use New without parentheses in PHP 8.4 
+
+Bad
+
+```php
+(new FooBar()).run();
+```
+
+Good
+
+```php
+new FooBar()->run();
+```

.github/instructions/test.instructions.md

@@ -0,0 +1,20 @@
+---
+applyTo: "**/{test,Test,tests,Tests}/**/*.php"
+---
+
+# Testing Instructions
+
+## PHPUnit Mock – Invocation Count Matchers
+
+Use `$this->` instead of `self::` for all count matchers.
+
+```php
+// Bad
+$mock->expects(self::once())->method('foo');
+
+// Good
+$mock->expects($this->once())->method('foo');
+```
+
+Applies to: `once()`, `never()`, `any()`, `exactly($n)`, `atLeastOnce()`, `atMost($n)`.
+

.gitignore

@@ -27,5 +27,9 @@ phpunit.xml
 .phpunit.cache
 .scannerwork
 
+# Docker #
+docker-compose.override.yml
+.env
+
 # Extra #
 !.gitkeep

AGENTS.md

@@ -0,0 +1,88 @@
+# Windwalker Framework – Agent Guide
+
+## Architecture Overview
+
+**Monorepo of 26+ standalone PHP packages** under `packages/`. Each package is independently installable via Composer
+but shares a unified dev environment at the root. The root `composer.json` maps all namespace prefixes (
+`Windwalker\{PackageName}\`) and autoloads each package's `src/bootstrap.php`.
+
+This repository ships the **components** consumed by the full Windwalker framework (`windwalker/windwalker`). It is not
+a runnable application.
+
+**PHP requirement:** ≥ 8.4.6. Code uses PHP 8.4 features (asymmetric visibility `public protected(set)`, named
+arguments, first-class callables).
+
+## Code Style
+
+- PSR-12 coding style.
+- Strict types (`declare(strict_types=1);` in all source files).
+- Docblocks only for non-obvious code; no redundant `@param`/`@return` when types are clear from signatures.
+- No global state or singletons; dependencies injected via constructors or method parameters.
+- No static methods except for pure utility functions (e.g. `StrInflector`, `Arr` or `Str`).
+- No facades or service locators; use explicit class references and dependency injection.
+- No global functions except for namespaced helpers defined in `functions.php` (e.g. `\Windwalker\collect()`,
+  `\Windwalker\raw()`). These are autoloaded via Composer's `files` autoloading and are not procedural global functions.
+- No magic methods (`__call`, `__get`, etc.) – all behavior should be explicit and discoverable via class methods and
+  properties.
+- No deprecated features or legacy patterns; the codebase is modern PHP 8.4+ and should not contain any legacy PHP 5/7
+  constructs.
+- Use PHP 8.5 property hooks with asymmetric visibility (`public protected(set)`) for properties prior than legacy
+  getter/setter methods. This allows read-only public access while still allowing internal mutation when necessary.
+
+All code style instructions see: `/.github/instructions/cs.instructions.md`.
+
+All test code style instructions see: `/.github/instructions/test.instructions.md`.
+
+## Package Layout
+
+Every package follows this structure:
+
+```
+packages/{name}/
+  src/              # PSR-4 source (Windwalker\{Name}\)
+  src/bootstrap.php # Loaded by Composer autoload files – registers closures/helpers
+  src/functions.php # Global helper functions (e.g. \Windwalker\collect(), \Windwalker\raw())
+  test/             # PHPUnit tests (Windwalker\{Name}\Test\)
+  composer.json     # Standalone package metadata
+  phpunit.xml.dist  # Per-package PHPUnit config
+```
+
+All source files begin with `declare(strict_types=1);`.
+
+## Developer Workflows
+
+### Running Tests
+
+```bash
+# All enabled tests (edit phpunit.xml to uncomment suites)
+php vendor/bin/phpunit
+
+# Single package suite
+php vendor/bin/phpunit --configuration packages/orm/phpunit.xml.dist
+
+# Database/HTTP tests require setup first:
+php -S localhost:8000 bin/test-server.php   # HTTP test server
+# Set WINDWALKER_TEST_DB_DSN_MYSQL in phpunit.xml
+```
+
+The root `phpunit.xml` is copied from `phpunit.xml.dist` and can be edited to enable/disable test suites. Each package
+also has its own `phpunit.xml.dist` for package-specific configuration (e.g. database DSN).
+
+### Test Base Classes
+
+- DB tests extend `AbstractDatabaseTestCase` (in `packages/database/src/Test/`).
+- ORM tests extend `AbstractORMTestCase` which wires `ORM` to a live DB adapter.
+- Executed SQL is logged to `packages/database/tmp/test-sql.sql` during test runs.
+
+## Project-Specific Conventions
+
+- **Global helpers** are namespaced functions, not procedural: e.g. `\Windwalker\collect([...])`,
+  `\Windwalker\raw($sql)`. Defined in `functions.php`, auto-loaded.
+- **Bootstrap files** (`src/bootstrap.php`) use autoload `files` – do not put heavy logic there; they mostly declare
+  global function aliases.
+- **Deprecated options key** for some array or int options has moved to `***Options` classes (e.g. `ORM::FOR_UPDATE` →
+  `new ORMOptions(forUpdate: true)`) – the old constants still exist but are marked deprecated.
+- **StrInflector** (`packages/utilities/src/StrInflector.php`) is used project-wide for singular/plural table alias
+  resolution (e.g. `Table` attribute alias defaults to `StrInflector::toSingular($tableName)`).
+- Each package's `composer.json` is also listed under `"replace"` in the root – this lets Composer treat the monorepo
+  root as all packages simultaneously.

composer.json

@@ -71,7 +71,8 @@
         "asika/simple-benchmark": "^3.0",
         "rize/uri-template": "^0.3.5||^0.4.0",
         "guzzlehttp/uri-template": "^1.0",
-        "asika/better-units": "^0.1.1"
+        "asika/better-units": "^0.1.1",
+        "symfony/cache": "^8.0"
     },
     "suggest": {
         "symfony/yaml": "Install ~4.0 if you require YAML support.",

docker-compose.override.yml.dist

@@ -0,0 +1,37 @@
+# Docker Local Override Configuration
+#
+# If you already have some services installed locally (e.g. MySQL, Redis), you can
+# copy the relevant service block into this file and adjust the ports mapping,
+# or remove that service entirely to connect to your local installation instead.
+# Update the host in phpunit.xml to localhost / 127.0.0.1 accordingly.
+#
+# Usage:
+#   cp docker-compose.override.yml.dist docker-compose.override.yml
+#
+# Example: remap MySQL to port 3307 to avoid conflicts with a local installation
+
+services:
+  # Uncomment to override the MySQL port (or remove the service to skip Docker MySQL)
+  # mysql:
+  #   ports:
+  #     - "3307:3306"
+  #   profiles:
+  #     - disabled
+
+  # postgresql:
+  #   ports:
+  #     - "5433:5432"
+  #   profiles:
+  #     - disabled
+
+  # redis:
+  #   ports:
+  #     - "6380:6379"
+  #   profiles:
+  #     - disabled
+
+  # memcached:
+  #   ports:
+  #     - "11212:11211"
+  #   profiles:
+  #     - disabled

docker-compose.yml

@@ -0,0 +1,61 @@
+services:
+  mysql:
+    image: mysql:8.4
+    container_name: windwalker_mysql
+    environment:
+      MYSQL_ROOT_PASSWORD: ut1234
+      MYSQL_DATABASE: windwalker_test
+    ports:
+      - "${MYSQL_PORT:-3306}:3306"
+    volumes:
+      - mysql_data:/var/lib/mysql
+      - ./docker/mysql/my.cnf:/etc/mysql/conf.d/windwalker.cnf:ro
+    healthcheck:
+      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "-ppassword"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+
+  postgresql:
+    image: postgres:17-alpine
+    container_name: windwalker_postgresql
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: ut1234
+      POSTGRES_DB: windwalker_test
+    ports:
+      - "${PGSQL_PORT:-5432}:5432"
+    volumes:
+      - postgresql_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+
+  redis:
+    image: redis:7-alpine
+    container_name: windwalker_redis
+    ports:
+      - "${REDIS_PORT:-6379}:6379"
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+
+  memcached:
+    image: memcached:1-alpine
+    container_name: windwalker_memcached
+    ports:
+      - "${MEMCACHED_PORT:-11211}:11211"
+
+volumes:
+  mysql_data:
+  postgresql_data:
+  redis_data:
+