feat: 支持 Laravel 13（双版并行 + v2.0.0）

.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": [
       {

.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

.gitignore

@@ -35,3 +35,6 @@ Thumbs.db
 .env.*
 !.env.testing
 !.env.example
+
+# Claude Code: 本地用户配置（含可能的 MCP token / 个人 hook 等），禁止提交
+.claude/settings.local.json

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<string>` 当作单条消息整体塞进新 MessageBag，PHPStan 在新版 Larastan / Laravel 13 类型签名下报错；修复为遍历每条字符串消息分别 add，行为更正确
+
 ## [1.2.2] - 2026-04-30
 
 ### Changed

README.md

@@ -6,8 +6,8 @@
     <a href="https://github.com/dcat-x/dcat-admin/actions"><img src="https://github.com/dcat-x/dcat-admin/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
     <a href="https://packagist.org/packages/dcat-x/laravel-admin"><img src="https://poser.pugx.org/dcat-x/laravel-admin/v/stable" alt="Latest Stable Version"></a>
     <a href="https://packagist.org/packages/dcat-x/laravel-admin"><img src="https://img.shields.io/packagist/dt/dcat-x/laravel-admin.svg" alt="Total Downloads"></a>
-    <a href="https://www.php.net/"><img src="https://img.shields.io/badge/php-8.2+-59a9f8.svg" alt="PHP Version"></a>
-    <a href="https://laravel.com/"><img src="https://img.shields.io/badge/laravel-12+-59a9f8.svg" alt="Laravel Version"></a>
+    <a href="https://www.php.net/"><img src="https://img.shields.io/badge/php-8.3+-59a9f8.svg" alt="PHP Version"></a>
+    <a href="https://laravel.com/"><img src="https://img.shields.io/badge/laravel-12%20%7C%2013-59a9f8.svg" alt="Laravel Version"></a>
     <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
 </p>
 
@@ -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+  |
 
 ## 安装
 

composer.json

@@ -30,20 +30,19 @@
         "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": {
         "fakerphp/faker": "^1.23",
         "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": {

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 代码，对后端开发者非常友好。
 
 <p align="center">
     <a href="https://github.com/dcat-x/dcat-admin/blob/main/LICENSE"><img style="display:inline" src="https://img.shields.io/badge/license-MIT-7389D8.svg?style=flat" ></a>
-    <a><img style="display:inline"  src="https://img.shields.io/badge/php-8.2+-59a9f8.svg?style=flat" /></a>
-    <a><img style="display:inline"  src="https://img.shields.io/badge/laravel-12+-59a9f8.svg?style=flat" ></a>
+    <a><img style="display:inline"  src="https://img.shields.io/badge/php-8.3+-59a9f8.svg?style=flat" /></a>
+    <a><img style="display:inline"  src="https://img.shields.io/badge/laravel-12%20%7C%2013-59a9f8.svg?style=flat" ></a>
 </p>
 
 ### 技术栈

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 仍接收安全修复。

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,19 +89,19 @@ 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 版本**
 
 ```bash
 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. ✅ 使用新功能优化代码
 

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;