升级指南

建议编辑

支持政策

在 Laravel Orchid，我们旨在为用户提供我们软件包的最佳支持。为了确保我们能够提供高效的支持，我们将仅为我们软件包的最新主要版本提供支持。这包括错误修复和安全更新。

我们建议您在项目中使用最新版本的 Laravel Orchid，以利用最新的功能、错误修复和安全更新。

如果您对我们的支持政策有任何疑问或顾虑，请随时与我们联系。

发布策略

我们相信保持我们的软件包现代化，因此遵循“早发布，常发布”的主要版本发布策略。这意味着我们不会等待很长时间才发布新的主要版本。通过更频繁地发布主要版本，新功能将更早可用，并且版本之间的升级将更易于管理。

我们尽量记录所有可能的重大更改。其中一些更改是内部调用，因此只有部分更改可能实际影响您的应用程序。

从 13.x 升级到 14.0

如果正确进行，从版本 13.x 升级到 14.0 可以是一个简单的过程。

在开始升级过程之前，备份现有应用程序并在开发环境中测试升级过程非常重要。这将确保在影响生产环境之前识别和解决任何意外问题。

更新依赖项

在您的 composer.json 文件中，将 orchid/platform 依赖项更新为 ^14.0

Laravel 10.x

现在需要 Laravel 10 来安装或升级。现有项目的更新说明可以在文档中找到。

保持状态

此版本的主要新功能之一是能够在屏幕上的操作之间保存公共属性的状态。

让我们举个例子。在 query 方法中查看屏幕时，我们可以设置将在 name/layouts 方法和其他方法中访问的公共属性。

现在，这些公共属性将被保存并可用于执行方法。

public $idea;

public function query() : array
{
    return [
        'idea' => Idea::first()
    ];
}

public function yourMethod()
{
    $this->idea; 
    // 属性不为空，并包含在开始时设置的值。
}

路由绑定

长期以来，Orchid 一直使用自己的解决方案来定义路由参数。 然而，对于绝大多数方法（query/method），使用了与控制器相同的解决方案。 这允许您定义：

Route::screen('/posts/{post:slug}', ExampleScreen::class);

Route::screen('/task', ExampleScreen::class)->withTrashed();

它还提供了其他未明确绑定到您习惯的内容的机会。

请注意，过去我们的教程有时会指定默认模型，这有时会导致参数为空。 但现在这会触发 404 错误。

监听器

以前，与监听器一起工作有时会让用户感到困惑。 因此，监听器不再具有指定屏幕方法的属性。 相反，存在一个名为 handler 的默认方法。 屏幕的当前状态作为第一个参数传递给此方法，request 对象作为第二个参数传递。

namespace App\Orchid\Layouts;

use Illuminate\Http\Request;
use Orchid\Screen\Fields\Input;
use Orchid\Screen\Layouts\Listener;
use Orchid\Screen\Repository;
use Orchid\Support\Facades\Layout;

class SubtractListener extends Listener
{
    /**
     * 将监听其值的字段名称列表。
     *
     * @var string[]
     */
    protected $targets = [
        'minuend',
        'subtrahend',
    ];

    /**
     * @return Layout[]
     */
    protected function layouts(): iterable
    {
        return [
            Layout::rows([
                Input::make('minuend')
                    ->title('第一个参数')
                    ->type('number'),

                Input::make('subtrahend')
                    ->title('第二个参数')
                    ->type('number'),

                Input::make('result')
                    ->readonly()
                    ->canSee($this->query->has('result')),
            ]),
        ];
    }

    /**
     * @param \Orchid\Screen\Repository $repository
     * @param \Illuminate\Http\Request  $request
     *
     * @return \Orchid\Screen\Repository
     */
    public function handle(Repository $repository, Request $request): Repository
    {
        [$minuend, $subtrahend] = $request->all();

        return $repository
            ->set('minuend', $minuend)
            ->set('subtrahend', $subtrahend)
            ->set('result', $minuend - $subtrahend);
    }
}

自动 HTTP 过滤和排序

自动过滤器以前基于用户输入的数据类型，这常常导致错误。 例如，当用户使用逗号搜索文本时，过滤器有时会将其识别为数组。 因此，现在需要明确指定过滤器的行为：

namespace App;

use Illuminate\Database\Eloquent\Model;
use Orchid\Filters\Filterable;
use Orchid\Filters\Types\Like;
use Orchid\Filters\Types\Where;

class Post extends Model
{
    use Filterable;

    protected $allowedFilters = [
        'id' => Where::class,
        'content' => Like::class,
    ];
}

另一个重要的变化是我们现在按原样获取列名。因此，您不能再对 JSON 字段使用点表示法。 我们正在努力寻找一种更高效和更安全的方法来处理 JSON 字段。

导航

在版本 14.0 中，个人资料下拉菜单已被移除。 建议在主菜单或屏幕上指定个人资料信息。 请确保从代码中删除对 Dashboard::MENU_PROFILE 常量和服务提供者的 registerProfileMenu 方法的引用。

例如，以下项目将不再正常工作：

public function registerProfileMenu(): array
{
    return [
        Menu::make('Documentation')
            ->title('Docs')
            ->icon('docs')
            ->url('https://orchid.software/en/docs'),
    ];
}

相反，请使用 registerMenu 方法定义菜单项：

public function registerMenu(): array
{
    return [
        Menu::make('Documentation')
            ->title('Docs')
            ->icon('docs')
            ->url('https://orchid.software/en/docs'),
    ];
}

所有依赖于 location 的方法不再需要此参数。例如，addMenuSubElements 方法现在直接指向目标 slug：

use Orchid\Support\Facades\Dashboard;

Dashboard::addMenuSubElements('sub-menu', [
    Menu::make('Sub element item 3')->icon('badge')
]);

图标

在新版本中，图标已更新为 Bootstrap 的一组。 虽然替换现有应用程序中的所有图标可能是一项挑战， 但您可以选择继续使用 Orchid 的图标。

为此，只需在您的 composer.json 文件中添加以下行：

"orchid/icons": "^2.0",

然后在您的配置文件中指定：

'icons' => [
    'orc' => \Orchid\IconPack\Path::getFolder(),
],

通过这样做，您将继续使用 Orchid 的图标集，由于缺乏设计师，已经有一段时间没有更新。

为了显示新图标，请添加：

'icons' => [
    // ...
    'bs' => \Orchid\Support\BootstrapIconsPath::getFolder(),
],

注销和退出模拟

“注销”和“退出模拟”操作的行为必须由开发人员明确定义。 为此，您可以将按钮定义添加到您的个人资料屏幕。

以下是定义这些按钮的示例：

use Orchid\Screen\Actions\Button;
use Orchid\Access\Impersonation;

public function commandBar(): iterable
{
    return [
        Button::make('返回我的账户')
            ->canSee(Impersonation::isSwitch())
            ->icon('bs.people')
            ->route('platform.switch.logout'),

        Button::make('退出')
            ->icon('bs.box-arrow-left')
            ->route('platform.logout'),
    ];
}
  • 第一个按钮“返回我的账户”用于退出模拟并返回到原始用户账户。此按钮仅在用户当前模拟另一个账户时可见。
  • 第二个按钮“退出”用于退出平台。

通过自行指定这些按钮的行为，您可以更好地控制 Orchid 应用程序中的退出和退出模拟操作。

从 12.x 升级到 13.0

更新依赖项

在您的 composer.json 文件中，将 orchid/platform 依赖项更新为 ^13.0

jQuery

此版本中不再默认包含 jQuery 包。如果需要，您可以单独安装它，例如在配置文件中添加引用：

'resource' => [
    'stylesheets' => [],
    'scripts'     => [
        'https://code.jquery.com/jquery-3.6.0.min.js'
    ],
],

Select2

由于 select2 依赖于 jQuery，它也被替换为 tom-select 包。我们尽量保持行为不变。但 select2 的特殊 JS 事件不再可用。

从 11.x 升级到 12.0

更新依赖项

在您的 composer.json 文件中，将 orchid/platform 依赖项更新为 ^12.0

Laravel 9.x

现在需要 Laravel 9 来安装或升级。现有项目的更新说明可以在文档中找到。

从 10.x 升级到 11.0

更新依赖项

在您的 composer.json 文件中，将 orchid/platform 依赖项更新为 ^11.0

发布资源文件

不再创建符号链接来下载资源，而是有一个新命令来发布它们：

php artisan orchid:publish

这会将 JS/CSS 文件放置在 public/vendor/orchid 目录中。还需要自动化对 composer.json 的更改：

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan orchid:publish --ansi"
        ]
    }
}

图标

图标现在可以完全替换，并且不强制加载。要继续使用它们，请更改配置文件：

'icons' => [
    'orc' => \Orchid\IconPack\Path::getFolder(),
],

屏幕

公共屏幕属性现在通过 query() 方法中的键自动填充。例如：

class IdeaScreen extends Screen
{
    public $name = 'Edit User';

    public function query(): array
    {
        return [
            'name' => 'Welcome',
        ];
    }
}

name 属性的值将被覆盖。 为了避免这种情况，请将属性的可见性更改为 protected

class IdeaScreen extends Screen
{
    protected $name = 'Edit User';

    public function query(): array
    {
        return [
            'name' => 'Welcome',
        ];
    }
}

组件

不再需要为组件指定预期的参数名称：

// 之前
TD::make('index')->component(OrderShortInformation::class, 'order', [
    'limit' => 100
]);

// 之后
TD::make('index')->component(OrderShortInformation::class, [
    'limit' => 100
]);

指标

不再使用单独的类，而是应用了简短语法：

use Orchid\Support\Facades\Layout;

public function query(): array
{
    return [
        'metrics' => [
            'sales'    => ['value' => number_format(6851), 'diff' => 10.08],
            'total'    => number_format(65661),
        ],
    ];
}
    
public function layout(): iterable
{
    return [
        Layout::metrics([
            '今日销售额'    => 'metrics.sales',
            '总收入' => 'metrics.total',
        ]),
    ];
}

从 9.x 升级到 10.0

更新依赖项

在您的 composer.json 文件中，将 orchid/platform 依赖项更新为 ^10.0

菜单

菜单的部分已减少，系统菜单已被移除。常量现在在 Orchid\Platform\Dashboard 类中。

use Orchid\Platform\Dashboard;

Dashboard::MENU_MAIN;
Dashboard::MENU_PROFILE;

菜单现在是 Field 类并且具有统一的语法。之前：

ItemMenu::label('Example screen')
    ->icon('monitor')
    ->route('platform.example')
    ->title('Navigation')
    ->badge(function () {
        return 6;
    });

之后：

use Orchid\Screen\Actions\Menu;

Menu::make('Example screen')
    ->icon('monitor')
    ->route('platform.example')
    ->title('Navigation')
    ->badge(function () {
        return 6;
    });

如您所见，更新应该非常温和。 但也会有差异，例如，嵌套元素的书写将更具视觉效果：

之前：

ItemMenu::label('Dropdown menu')
    ->slug('example-menu')
    ->icon('code')
    ->withChildren(),

ItemMenu::label('Sub element item 1')
    ->place('example-menu')
    ->icon('bag'),

ItemMenu::label('Sub element item 2')
    ->place('example-menu')
    ->icon('heart'),

之后：

Menu::make('Dropdown menu')
    ->icon('code')
    ->list([
        Menu::make('Sub element item 1')->icon('bag'),
        Menu::make('Sub element item 2')->icon('heart'),
    ]),

默认排序已从 1000 更改为 0：

Menu::make('Example screen')
    ->icon('monitor')
    ->route('platform.example')
    ->title('Navigation')
    ->sort(2),

这也适用于嵌套元素：

Menu::make('Dropdown menu')
    ->icon('code')
    ->list([
        Menu::make('Sub element item 1')->icon('bag')->sort(2),
        Menu::make('Sub element item 2')->icon('heart')->sort(0),
    ]),

对于动态定义，您需要添加一个 slug 方法，在其中传递一个唯一字符串：

Menu::make('Dropdown menu')
    ->slug('sub-menu')
    ->icon('code')
    ->list([
        Menu::make('Sub element item 1')->icon('bag'),
        Menu::make('Sub element item 2')->icon('heart'),
    ]),

然后在我们自己的包中添加新项目，如：

Dashboard::addMenuSubElements(Dashboard::MENU_MAIN, 'sub-menu', [
   Menu::make('Sub element item 3')->icon('badge')
]);

警告。 如果菜单是延迟使用的，则需要遵循加载顺序

CanSee

现在 Fields/Layouts/TD 具有一个通用特性。没有任何限制。现在您可以这样做：

Input::make()->canSee(false);
TD::make()->canSee(false);
Layout::rows([])->canSee(false);

但现在层内的定义不同

// 之前
public function canSee(Repository $query): bool
{
    return ...;
}

// 之后
public function isSee(): bool
{
    return ...;
}

Stimulus

Stimulus 框架已更新到版本 2.0。保留了向后兼容性，但控制器名称去掉了前缀：

<!--  之前: -->
<div data-controller="fields--checkbox">

<!--  之后: -->
<div data-controller="checkbox">

Turbo

Turbolinks 库已更新为 Turbo，更多详细信息请参见：https://turbo.hotwire.dev/

如果您使用了自己的 js 脚本，则建议阅读它们的更改。例如：

// 之前
document.addEventListener("turbolinks:load", function() {
    // ...
})

// 之后
document.addEventListener("turbo:load", function() {
  // ...
})

Compendium

Compendium 类已被移除。建议使用较新的 Legend。

Collapse

Collapse 类已被移除。

从 8.x 升级到 9.0

更新依赖项

在您的 composer.json 文件中，将 orchid/platform 依赖项更新为 ^9.0

认证

Laravel 团队推出了新的产品 Jetstream 和 Fortify，它们取代了早期的 laravel/ui。为了确保与各种选项的兼容性，laravel/ui 的依赖已被移除。以及恢复密码的功能。

新产品提供了用户的双因素身份验证，以及查看最后活跃会话的功能。为了不与它们竞争，相同的功能已从包中移除。

虽然迁移已被移除，但存储在数据库中的数据不会自动删除。要删除它们，您需要执行以下 SQL 代码：

ALTER TABLE "users"
    DROP COLUMN "last_login"
    DROP COLUMN "uses_two_factor_auth"
    DROP COLUMN "two_factor_secret_code"
    DROP COLUMN "two_factor_recovery_code";

DELETE FROM migrations
WHERE migration = '2020_06_07_184338_added_columns_for_2fa';

之后，您需要从用户模型中删除列数据。 如果您在项目中复制了迁移 2020_06_07_184338_added_columns_for_2fa，请不要忘记删除它。

从 7.x 升级到 8.0

更新依赖项

在您的 composer.json 文件中，将 orchid/platform 依赖项更新为 ^8.0

TinyMCE 编辑器

HTML 编辑器已从标准发行版中移除。代码已移至单独的仓库。

设置模型

设置模型也已被移除。存储在数据库中的数据不会自动删除。 要删除它们，您需要执行以下 SQL 代码：

如果您在项目中复制了迁移 2015_12_02_181214_create_table_settings，请不要忘记删除它。

DROP TABLE settings;

DELETE FROM migrations
WHERE migration = '2015_12_02_181214_create_table_settings';

源代码可以作为单独的包进行安装。

面包屑

包 davejamesmiller/laravel-breadcrumbs 被替换为 tabuna/breadcrumbs 并应在更新依赖项时自动安装。

注意： 可能需要删除 bootstrap/cache 目录中的启动缓存文件。

新包的语法允许您直接在路由定义中显示面包屑：

Route::screen('example', ExampleScreen::class)
    ->name('platform.example')
    ->breadcrumbs(function (Trail $trail) {
        return $trail->parent('platform.index')->push(__('Example screen'));
    });

或者，您可以继续使用单独的文件。 为此，您需要在服务提供者中加载它：

namespace App\Providers;

use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * 启动应用程序事件。
     *
     * @return void
     */
    public function boot()
    {
        require base_path('routes/breadcrumbs.php');
    }
}

如果您使用了完整的类名，则需要将它们替换为类似的：

use Tabuna\Breadcrumbs\Breadcrumbs;
use Tabuna\Breadcrumbs\Trail;

屏幕更改

构造函数

不再需要传递 Request 对象和调用父类。之前：

class PublicationScreen extends Screen
{
    public function __construct(Request $request, Locator $locator)
    {
        $this->request = $request;
        $this->locator = $locator;
    }
}

定义现在看起来像这样：

class PublicationScreen extends Screen
{
    public function __construct(Locator $locator)
    {
        $this->locator = $locator;
    }
}

路由方法

未使用的方法已被移除。无法通过 PUT|PATCH|DELETE 方法访问屏幕，调用必须使用 GET|POSTS 来接收/发送数据。

Method           | URI                                  | Name
-----------------+--------------------------------------+--------------
GET|HEAD|POST    | dashboard/idea/{method?}             | platform.idea

现在，等待模型的屏幕方法，如果不存在，将实现一个空模型以及控制器。更多。

数据欺骗（异步）

地址栏中的 {argument?} 期望已被移除。 现在使用单独的路由进行调用：

$this->router
    ->post('async/{screen}/{method?}/{template?}', [AsyncController::class, 'load'])
    ->name('async');

布局

每个层现在继承自 Orchid\Screen\Layout 类，而不是 Orchid\Screen\Layouts\Base。

要通过简短语法声明层，现在应使用 Orchid\Support\Facades\Layout facade，而不是 Orchid\Screen\Layout 类。

之前：

use Orchid\Screen\Layout;

Layout::row([
     // ...
]);

之后：

use Orchid\Support\Facades\Layout;

Layout::row([
     // ...
]);

发布消息

系统消息通知用户已发布新版本的软件包。但他们无法在没有开发人员帮助的情况下更新。 这比保持软件更新更令人烦恼。因此，它被移除，如果您使用它（默认仅在第一个屏幕上），那么您也应该删除其调用以及 blade 模板。屏幕调用示例：

return [
    'status' => Dashboard::checkUpdate(),
];

在屏幕中使用模板：

Layout::view('platform::partials.update');

图标

图标显示已从 font 更改为 SVG 格式。 现在 ->icon 方法不接受设置的 css 值，而是文件名。 在大多数情况下，您只需删除 icon- 前缀。

我们的朋友

探索 更多内容。

社区准则 捐赠

GitHub 讨论 HIG 许可证

简体中文 / English / Russian