From 37c8d891d663ec30fc35e5990ef9d47213d0b99c Mon Sep 17 00:00:00 2001 From: Cooper Date: Thu, 30 Apr 2026 15:37:36 +0800 Subject: [PATCH 1/3] =?UTF-8?q?chore(claude):=20=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E7=BA=A7=20Claude=20Code=20=E9=85=8D=E7=BD=AE=E5=81=A5?= =?UTF-8?q?=E5=BA=B7=E4=BC=98=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - .gitignore: 新增 .claude/settings.local.json 忽略规则 防止 Claude Code 自动生成的本地用户配置（含可能的 MCP token 等）误提交 - .claude/settings.json: 新增 enabledPlugins 项目级覆盖 关闭与本 PHP/Laravel 项目无关的 5 个 LSP 插件（gopls/jdtls/pyright/rust-analyzer/typescript）， 减少启动期 commands/skills 注入与供应链入口 --- .claude/settings.json | 7 +++++++ .gitignore | 3 +++ 2 files changed, 10 insertions(+) diff --git a/.claude/settings.json b/.claude/settings.json index 198586a..86ae476 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,4 +1,11 @@ { + "enabledPlugins": { + "gopls-lsp@claude-plugins-official": false, + "jdtls-lsp@claude-plugins-official": false, + "pyright-lsp@claude-plugins-official": false, + "rust-analyzer-lsp@claude-plugins-official": false, + "typescript-lsp@claude-plugins-official": false + }, "hooks": { "PostToolUse": [ { diff --git a/.gitignore b/.gitignore index 4969084..f99f830 100644 --- a/.gitignore +++ b/.gitignore @@ -35,3 +35,6 @@ Thumbs.db .env.* !.env.testing !.env.example + +# Claude Code: 本地用户配置（含可能的 MCP token / 个人 hook 等），禁止提交 +.claude/settings.local.json From f7deaa0702677efa2fa034cd1bb9432fc642ec62 Mon Sep 17 00:00:00 2001 From: Cooper Date: Fri, 1 May 2026 08:04:42 +0800 Subject: [PATCH 2/3] =?UTF-8?q?feat:=20=E6=94=AF=E6=8C=81=20Laravel=2013?= =?UTF-8?q?=EF=BC=88=E5=8F=8C=E7=89=88=E5=B9=B6=E8=A1=8C=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 依赖约束: - php: ^8.2 → ^8.3 (Laravel 13 最低要求) - laravel/framework: ^12.0 → ^12.0||^13.0 - orchestra/testbench: ^10.0 → ^10.0||^11.0 - phpunit/phpunit: ^11.0 → ^11.0||^12.0 - spatie/eloquent-sortable: ^4.0 → ^4.0||^5.0 - 移除 doctrine/dbal: src 零引用，Laravel 11+ 已不需要 代码修复: - src/Form/Field/ListField.php formatValidatorMessages() 修正: 原代码把 MessageBag::toArray() 返回的 array 整体当作单条 message, 实为 bug; Laravel 13 的 MessageBag::add() 收紧类型签名时被 PHPStan 揭出. 修复为遍历每条字符串消息分别 add. CI 矩阵 (.github/workflows/tests.yml): - 主分片 (PHP 8.3 + Laravel 12): unit-a / unit-gh / unit-misc 三段 - 兼容烟测: PHP 8.4 + Laravel 12 / PHP 8.3 + Laravel 13 / PHP 8.4 + Laravel 13 - 通过 matrix.laravel 条件 composer require 切换 testbench/phpunit/sortable 版本 文档: - README 兼容矩阵新增 v2.x 行 (Laravel 12.x/13.x, PHP 8.3+) - CHANGELOG Unreleased 段写明 breaking changes (PHP 8.3+, doctrine/dbal 移除) 本地双版验证通过: - Laravel 12 + PHP 8.3: 5027 tests / 8071 assertions, exit 0 - Laravel 13 + PHP 8.3: 5027 tests / 8071 assertions, exit 0 --- .github/workflows/tests.yml | 44 +++++++++++++++++++++++++++++++----- CHANGELOG.md | 13 +++++++++++ README.md | 11 +++++---- composer.json | 11 ++++----- src/Form/Field/ListField.php | 6 +++-- 5 files changed, 66 insertions(+), 19 deletions(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 79a6a3d..66907ed 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -44,23 +44,39 @@ jobs: fail-fast: false matrix: include: + # PHP 8.3 + Laravel 12（主分片矩阵：完整覆盖） - php: '8.3' + laravel: '12' suite: 'tests/Unit/Actions tests/Unit/Console tests/Unit/Contracts tests/Unit/Exception tests/Unit/Extend tests/Unit/Form' label: 'unit-a' - php: '8.3' + laravel: '12' suite: 'tests/Unit/Grid tests/Unit/Http' label: 'unit-gh' - php: '8.3' + laravel: '12' suite: 'tests/Feature tests/Unit/ApplicationTest.php tests/Unit/AdminTest.php tests/Unit/ColorTest.php tests/Unit/FormTest.php tests/Unit/GridTest.php tests/Unit/AdminServiceProviderTest.php tests/Unit/ShowTest.php tests/Unit/Layout tests/Unit/Models tests/Unit/Octane tests/Unit/Repositories tests/Unit/Scaffold tests/Unit/Services tests/Unit/Show tests/Unit/Support tests/Unit/Traits tests/Unit/Tree tests/Unit/Widgets' label: 'unit-misc' - - php: '8.2' + + # PHP 8.4 + Laravel 12（兼容性烟测，跑核心套件） + - php: '8.4' + laravel: '12' + suite: 'tests/Feature tests/Unit/ApplicationTest.php tests/Unit/AdminTest.php tests/Unit/ColorTest.php tests/Unit/FormTest.php tests/Unit/GridTest.php tests/Unit/AdminServiceProviderTest.php tests/Unit/ShowTest.php' + label: 'compat-smoke' + + # PHP 8.3 + Laravel 13（新版本，跑核心套件） + - php: '8.3' + laravel: '13' suite: 'tests/Feature tests/Unit/ApplicationTest.php tests/Unit/AdminTest.php tests/Unit/ColorTest.php tests/Unit/FormTest.php tests/Unit/GridTest.php tests/Unit/AdminServiceProviderTest.php tests/Unit/ShowTest.php' - label: 'compat-smoke-82' + label: 'l13-smoke' + + # PHP 8.4 + Laravel 13（推荐生产组合，跑核心套件） - php: '8.4' + laravel: '13' suite: 'tests/Feature tests/Unit/ApplicationTest.php tests/Unit/AdminTest.php tests/Unit/ColorTest.php tests/Unit/FormTest.php tests/Unit/GridTest.php tests/Unit/AdminServiceProviderTest.php tests/Unit/ShowTest.php' - label: 'compat-smoke-84' + label: 'l13-recommended' - name: PHP ${{ matrix.php }} / ${{ matrix.label }} + name: PHP ${{ matrix.php }} / Laravel ${{ matrix.laravel }} / ${{ matrix.label }} steps: - name: Checkout code @@ -74,8 +90,24 @@ jobs: coverage: none cache: composer + - name: Lock Laravel 13 stack + if: matrix.laravel == '13' + env: + LARAVEL_VERSION: ${{ matrix.laravel }} + run: | + composer require \ + "laravel/framework:^13.0" \ + "spatie/eloquent-sortable:^5.0" \ + --no-update --no-interaction + composer require --dev \ + "orchestra/testbench:^11.0" \ + "phpunit/phpunit:^12.0" \ + --no-update --no-interaction + - name: Install dependencies - run: composer install --prefer-dist --no-interaction --no-progress + run: composer update --prefer-dist --no-interaction --no-progress - name: Run tests - run: vendor/bin/phpunit ${{ matrix.suite }} + env: + SUITE: ${{ matrix.suite }} + run: vendor/bin/phpunit $SUITE diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e1f902..80b48fa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Breaking Changes + +- **PHP 最低版本提升至 8.3** — Laravel 13 要求 PHP 8.3+，对应 dcat-admin 升至 v2.0.0；PHP 8.2 用户请继续使用 v1.x（仍维护安全修复） +- **移除 `doctrine/dbal` 依赖** — Laravel 11+ 已不再依赖该包，源码全程零引用，从 require 中移除以减少依赖图体积；如外部项目曾依赖此传递依赖，请显式 `composer require doctrine/dbal` + +### Added + +- **支持 Laravel 13** — `laravel/framework: ^12.0||^13.0`、`orchestra/testbench: ^10.0||^11.0`、`spatie/eloquent-sortable: ^4.0||^5.0`、`phpunit/phpunit: ^11.0||^12.0`，CI 双版矩阵覆盖 PHP 8.3/8.4 × Laravel 12/13 + +### Fixed + +- **`ListField::formatValidatorMessages()` 数组消息处理** — 此前把 `MessageBag::toArray()` 返回的 `array` 当作单条消息整体塞进新 MessageBag，PHPStan 在新版 Larastan / Laravel 13 类型签名下报错；修复为遍历每条字符串消息分别 add，行为更正确 + ## [1.2.2] - 2026-04-30 ### Changed diff --git a/README.md b/README.md index b18d047..df464b0 100755 --- a/README.md +++ b/README.md @@ -6,8 +6,8 @@ Tests Latest Stable Version Total Downloads - PHP Version - Laravel Version + PHP Version + Laravel Version License

@@ -34,9 +34,10 @@ Dcat Admin 只需很少的代码即可快速构建出一个功能完善的高颜 ## 版本兼容 -| Dcat Admin X | Laravel | PHP | -|--------------|---------|-------| -| 1.x | 12.x | 8.2+ | +| Dcat Admin X | Laravel | PHP | +|--------------|------------|-------| +| 2.x | 12.x, 13.x | 8.3+ | +| 1.x | 12.x | 8.2+ | ## 安装 diff --git a/composer.json b/composer.json index 4bb1bbf..70199e3 100755 --- a/composer.json +++ b/composer.json @@ -30,10 +30,9 @@ "source": "https://github.com/dcat-x/dcat-admin" }, "require": { - "php": "^8.2", - "laravel/framework": "^12.0", - "spatie/eloquent-sortable": "^4.0", - "doctrine/dbal": "^4.0", + "php": "^8.3", + "laravel/framework": "^12.0||^13.0", + "spatie/eloquent-sortable": "^4.0||^5.0", "dcat-x/easy-excel": "^1.0" }, "require-dev": { @@ -41,9 +40,9 @@ "larastan/larastan": "^3.0", "laravel/pint": "^1.0", "mockery/mockery": "^1.6", - "orchestra/testbench": "^10.0", + "orchestra/testbench": "^10.0||^11.0", "phpstan/phpstan": "^2.0", - "phpunit/phpunit": "^11.0", + "phpunit/phpunit": "^11.0||^12.0", "rector/rector": "^2.0" }, "autoload": { diff --git a/src/Form/Field/ListField.php b/src/Form/Field/ListField.php index e86615a..8f005c5 100644 --- a/src/Form/Field/ListField.php +++ b/src/Form/Field/ListField.php @@ -120,8 +120,10 @@ public function formatValidatorMessages($messageBag) { $messages = new MessageBag; - foreach ($messageBag->toArray() as $column => $message) { - $messages->add($this->column, $message); + foreach ($messageBag->toArray() as $messagesPerField) { + foreach ($messagesPerField as $message) { + $messages->add($this->column, $message); + } } return $messages; From 1b20ba35f5bad08c8d284159e0ce70319630f522 Mon Sep 17 00:00:00 2001 From: Cooper Date: Fri, 1 May 2026 08:09:10 +0800 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E8=87=B3=20Dcat=20Admin=20X=202.x=EF=BC=88Laravel=201?= =?UTF-8?q?3=20+=20PHP=208.3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - introduction.md: 描述与 badge 由 PHP 8.2+ / Laravel 12+ 改为 PHP 8.3+ / Laravel 12 | 13 - upgrade-from-original.md: - 当前版本表与对比表新增 2.x 列 - PHP/Laravel 检查命令措辞同时覆盖 1.x 与 2.x - composer.json 示例改用 ^8.3 / ^12.0||^13.0 / ^2.0 - 章节标题与措辞同步至 PHP 8.3+ / Laravel 12 / 13 - 总结清单更新 - update.md 末尾新增「从 1.x 升级到 2.x」章节，覆盖： - PHP/Laravel/doctrine-dbal 三项破坏性变更 - 升级步骤与示例 - doctrine/dbal 自托管说明 - L12 → L13 分两步走建议 - 留在 1.x 的兼容方案 --- docs/getting-started/introduction.md | 6 +- docs/getting-started/update.md | 62 +++++++++++++++++++ docs/getting-started/upgrade-from-original.md | 44 ++++++------- 3 files changed, 88 insertions(+), 24 deletions(-) diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md index f184270..ffe1547 100644 --- a/docs/getting-started/introduction.md +++ b/docs/getting-started/introduction.md @@ -3,12 +3,12 @@ `Dcat Admin` 是一个基于 [laravel-admin](https://github.com/z-song/laravel-admin) 二次开发而成的后台系统构建工具。 -`Dcat Admin X` 是基于 [Dcat Admin](https://github.com/jqhph/dcat-admin) 的继续维护版本，适配 Laravel 12+ 和 PHP 8.2+，只需极少的代码即可快速构建出一个功能完善的高颜值后台系统。支持页面一键生成 CRUD 代码，内置丰富的后台常用组件，开箱即用，让开发者告别冗杂的 HTML 代码，对后端开发者非常友好。 +`Dcat Admin X` 是基于 [Dcat Admin](https://github.com/jqhph/dcat-admin) 的继续维护版本，适配 Laravel 12 / Laravel 13 与 PHP 8.3+，只需极少的代码即可快速构建出一个功能完善的高颜值后台系统。支持页面一键生成 CRUD 代码，内置丰富的后台常用组件，开箱即用，让开发者告别冗杂的 HTML 代码，对后端开发者非常友好。

- - + +

### 技术栈 diff --git a/docs/getting-started/update.md b/docs/getting-started/update.md index fdd1328..d433aa2 100644 --- a/docs/getting-started/update.md +++ b/docs/getting-started/update.md @@ -56,3 +56,65 @@ php artisan admin:publish --force --assets ```bash php artisan admin:publish --force --migrations ``` + +--- + +### 从 1.x 升级到 2.x（支持 Laravel 13） + +2.x 是包含**破坏性变更**的主版本，主要变化： + +| 项目 | 1.x | 2.x | +|---|---|---| +| PHP 最低版本 | 8.2 | **8.3** | +| Laravel 支持 | 12.x | 12.x / **13.x** | +| `doctrine/dbal` 依赖 | `^4.0`（实际未使用） | **已移除** | + +#### 升级步骤 + +1. **升级 PHP 到 8.3+** + +如果当前 PHP 版本是 8.2，需要先升级到 8.3 或 8.4。 + +2. **更新 composer.json** + +```json +{ + "require": { + "php": "^8.3", + "laravel/framework": "^12.0||^13.0", + "dcat-x/laravel-admin": "^2.0" + } +} +``` + +```bash +composer update +php artisan admin:update +``` + +3. **关于 `doctrine/dbal`** + +2.x 不再依赖 `doctrine/dbal`。dcat-admin 源码不使用该包，Laravel 11+ 已不依赖它做 schema 操作。如果你的项目代码本身在用 `doctrine/dbal`（比如自定义 schema 操作），请显式声明： + +```bash +composer require doctrine/dbal +``` + +4. **是否升级到 Laravel 13？** + +2.x 同时支持 Laravel 12 和 13，可分两步走： + +- **第一步**：先升 dcat-admin 到 2.x（仍跑 Laravel 12），跑全测试确认无影响 +- **第二步**：参考 [Laravel 13 升级指南](https://laravel.com/docs/13.x/upgrade)，再升级框架本身 + +> Laravel 13 官方宣称"零破坏性变更"，对应用代码的影响较小；详见上游升级文档。 + +#### 不能升级时 + +如需停留在 PHP 8.2 / Laravel 12，请固定 dcat-admin 1.x： + +```json +"dcat-x/laravel-admin": "^1.0" +``` + +1.x 仍接收安全修复。 diff --git a/docs/getting-started/upgrade-from-original.md b/docs/getting-started/upgrade-from-original.md index c7da0fa..589d3ed 100644 --- a/docs/getting-started/upgrade-from-original.md +++ b/docs/getting-started/upgrade-from-original.md @@ -13,20 +13,20 @@ ### Dcat Admin X (本项目) -- **当前版本**: 1.x -- **Laravel 支持**: 12.x -- **PHP 支持**: 8.2+ +- **当前版本**: 2.x（v1.x 仍维护安全修复） +- **Laravel 支持**: 12.x / 13.x +- **PHP 支持**: 8.3+ - **维护状态**: 持续维护 ## 主要变化 ### 1. 环境要求 -| 项目 | 原版 Dcat Admin | Dcat Admin X | -|------|----------------|--------------| -| PHP | 7.1 - 8.1 | 8.2+ | -| Laravel | 5.5 - 9.x | 12.x | -| Composer 包名 | `dcat/laravel-admin` | `dcat-x/laravel-admin` | +| 项目 | 原版 Dcat Admin | Dcat Admin X 1.x | Dcat Admin X 2.x | +|------|----------------|------------------|------------------| +| PHP | 7.1 - 8.1 | 8.2+ | 8.3+ | +| Laravel | 5.5 - 9.x | 12.x | 12.x / 13.x | +| Composer 包名 | `dcat/laravel-admin` | `dcat-x/laravel-admin` | `dcat-x/laravel-admin` | ### 2. 新增功能 @@ -89,7 +89,7 @@ cp -r /path/to/project /path/to/project-backup php -v ``` -确保 PHP 版本 >= 8.2。如果不满足,需要先升级 PHP。 +Dcat Admin X 2.x 要求 PHP >= 8.3；1.x 要求 PHP >= 8.2。如果不满足，需要先升级 PHP。 4. **检查 Laravel 版本** @@ -97,11 +97,11 @@ php -v php artisan --version ``` -如果 Laravel 版本 < 12.x,需要先升级 Laravel。 +Dcat Admin X 2.x 支持 Laravel 12.x 与 13.x；1.x 仅支持 12.x。如果 Laravel 版本低于支持范围，需要先升级 Laravel。 ### 升级 Laravel (如需要) -如果当前 Laravel 版本低于 12.x,请参考 [Laravel 升级指南](https://laravel.com/docs/12.x/upgrade) 进行升级。 +如果计划使用 Dcat Admin X 2.x，建议升级到 Laravel 13.x。请参考 [Laravel 13 升级指南](https://laravel.com/docs/13.x/upgrade) 或 [Laravel 12 升级指南](https://laravel.com/docs/12.x/upgrade)。 主要步骤: @@ -119,13 +119,15 @@ php artisan --version ```json { "require": { - "php": "^8.2", - "laravel/framework": "^12.0", - "dcat-x/laravel-admin": "^1.0" + "php": "^8.3", + "laravel/framework": "^12.0||^13.0", + "dcat-x/laravel-admin": "^2.0" } } ``` +> 如需停留在 PHP 8.2 / Laravel 12，请使用 `dcat-x/laravel-admin: ^1.0`。 + 移除原版 Dcat Admin: ```bash @@ -211,9 +213,9 @@ use Dcat\Admin\Show; use Dcat\Admin\Layout\Content; ``` -### 2. PHP 8.2+ 语法适配 +### 2. PHP 8.3+ 语法适配 -需要注意 PHP 8.2+ 的语法变化: +需要注意 PHP 8.2/8.3 的语法变化（Dcat Admin X 2.x 要求 PHP 8.3+）: #### 动态属性 @@ -264,7 +266,7 @@ public function show($id) } ``` -### 3. Laravel 12 API 适配 +### 3. Laravel 12 / 13 API 适配 #### 字符串辅助函数 @@ -292,7 +294,7 @@ $result = Arr::get($array, 'key', 'default'); ### 4. 数据库查询 -Laravel 12 的查询构建器更严格: +Laravel 12 / 13 的查询构建器更严格: ```php // 原代码 @@ -456,7 +458,7 @@ $grid->column('price')->fee('¥', 2); ### 2. 代码优化 -利用 PHP 8.2+ 新特性优化代码: +利用 PHP 8.3+ 新特性优化代码: ```php // 使用 match 表达式 @@ -501,11 +503,11 @@ php artisan octane:install 升级到 Dcat Admin X 的主要步骤: -1. ✅ 确保环境满足要求 (PHP 8.2+, Laravel 12+) +1. ✅ 确保环境满足要求 (Dcat Admin X 2.x: PHP 8.3+, Laravel 12.x / 13.x) 2. ✅ 备份数据库和代码 3. ✅ 更新 Composer 依赖 4. ✅ 发布资源和更新配置 -5. ✅ 适配 PHP 8.2+ 和 Laravel 12 API +5. ✅ 适配 PHP 8.3+ 和 Laravel 12 / 13 API 6. ✅ 测试所有功能 7. ✅ 使用新功能优化代码