升级指南

依赖项升级

Nova 的上游依赖项已升级。您将在下面找到我们的依赖项升级完整列表

服务器

PHP 7.3+
Laravel 框架 8.0+
将 doctrine/dbal 从 ^2.9 更新至 ^2.13.3|^3.1.2|^4.0
将 laravel/ui 从 ^2.0|^3.0 更新至 ^3.3|^4.0
将 symfony/* 从 ^5.0 更新至 ^5.4|^6.0|^7.0
已移除 cakephp/chronos 和 moontoast/math 依赖项

客户端

将受支持的 Laravel Mix 版本从 v1 更新至 v6
已移除 flatpickr 和 moment.js

更新 Composer 依赖项

您应在应用程序的 composer.json 文件中将 laravel/nova 依赖项更新至 ^4.0

json

"laravel/nova": "^4.0",

购买 Nova 4.0 许可证后，您应更新 Composer auth.json 文件，以使用您新生成的许可证密钥，而不是您之前的 Nova 3 API 令牌或帐户密码。

接下来，安装您更新的 Composer 依赖项

shell

composer update mirrors

composer update

更新应用程序的 Composer 依赖项后，您应迁移数据库

shell

php artisan migrate

更新配置、资产和翻译

接下来，您应更新应用程序的 Nova 配置、资产和翻译文件。为开始，您可以运行以下命令以更新您的资产和翻译。

您可能希望在运行此命令前存储当前翻译文件副本，以便在运行这些命令后轻松将任何自定义翻译移植回新文件。此外，我们将为您的 Nova 安装生成一个“主”仪表盘

bash

php artisan nova:dashboard Main

php -r "file_exists('./resources/views/vendor/nova/layout.blade.php') && unlink('./resources/views/vendor/nova/layout.blade.php');"

php artisan vendor:publish --tag=nova-assets --force
php artisan vendor:publish --tag=nova-lang --force
php artisan view:clear

接下来，让我们更新 Nova 配置文件。首先，确保应用程序的 `nova` 配置文件中的 `middleware` 和 `api_middleware` 配置选项如下所示

php

use Laravel\Nova\Http\Middleware\Authenticate;
use Laravel\Nova\Http\Middleware\Authorize;
use Laravel\Nova\Http\Middleware\BootTools;
use Laravel\Nova\Http\Middleware\DispatchServingNovaEvent;
use Laravel\Nova\Http\Middleware\HandleInertiaRequests;

return [

    // ...

    'middleware' => [
        'web',
        HandleInertiaRequests::class,
        DispatchServingNovaEvent::class,
        BootTools::class,
    ],

    'api_middleware' => [
        'nova',
        Authenticate::class,
        Authorize::class,
    ],

    // ...
];

接下来，确保应用程序的 `nova` 配置文件包含一个 `storage_disk` 配置选项

php

'storage_disk' => env('NOVA_STORAGE_DISK', 'public'),

更新配置后，您应查看以下更改列表并相应地升级应用程序。

注册 Nova 许可证密钥和生产 URL

Nova 要求许可证密钥和生产 URL 在生产环境中使用。Nova 将根据 Nova 帐户中找到的许可证详细信息中的值检查您的许可证密钥和当前主机。您可以在安装文档中了解更多信息。

更新第三方 Nova 包

如果您的应用程序依赖于第三方开发的 Nova 工具或包，则这些包可能尚未与 Nova 4.0 兼容，并且需要其维护者更新。

高影响更改

Nova 请求

Nova 4 更新了各种方法以接受 `Laravel\Nova\Http\Requests\NovaRequest` 实例，而不是 `Illuminate\Http\Request` 实例。下面提供了已更新方法的概述，以便您可以相应地更新方法签名。

资源

fields、fieldsForIndex、fieldsForDetail、fieldsForCreate、fieldsForUpdate、cards、filters、lenses 和 actions 方法

php

class Resource
{
    public function fields(NovaRequest $request) {}
    public function fieldsForIndex(NovaRequest $request) {}
    public function fieldsForDetail(NovaRequest $request) {}
    public function fieldsForCreate(NovaRequest $request) {}
    public function fieldsForUpdate(NovaRequest $request) {}
    public function cards(NovaRequest $request) {}
    public function filters(NovaRequest $request) {}
    public function lenses(NovaRequest $request) {}
    public function actions(NovaRequest $request) {}
}

透镜

fields、filters 和 actions 方法

php

class Lens
{
    public function fields(NovaRequest $request) {}
    public function cards(NovaRequest $request) {}
    public function filters(NovaRequest $request) {}
    public function actions(NovaRequest $request) {}
}

操作

fields 方法

php

class Action
{
    public function fields(NovaRequest $request) {}
}

筛选器

apply 和 options 方法

php

class Filter
{
    public function apply(NovaRequest $request, $query, $value) {}
    public function options(NovaRequest $request) {}
}

主仪表盘类

在 Nova 的早期版本中，“主”仪表盘卡片是通过应用程序的 NovaServiceProvider 的 cards 方法定义的。然而，在 Nova 4 中，必须通过以下命令创建一个专门的 Main 仪表盘类

bash

php artisan nova:dashboard Main

接下来，将 NovaServiceProvider 中 cards 方法的内容移动到新 App\Nova\Dashboards\Main 类的 cards 方法，并在 NovaServiceProvider 的 dashboards 方法中注册 Main 仪表盘

php

use App\Nova\Dashboards\Main;

/**
 * Get the extra dashboards that should be displayed on the Nova dashboard.
 *
 * @return array
 */
protected function dashboards()
{
    return [
        new Main,
    ];
}

仪表盘方法

在 Nova 4 中，仪表盘类上定义的 label 和 uriKey 方法不再是静态的。你应该相应地更新你的方法

php

/**
 * Get the displayable name of the dashboard.
 *
 * @return string
 */
public function label()
{
    return 'Post Stats';
}

/**
 * Get the URI key for the dashboard.
 *
 * @return string
 */
public function uriKey()
{
    return 'posts-dashboard';
}

客户端时区检测

Nova 4 删除了依赖客户端计算机时区以显示时区相关信息的功能。相反，Nova 4 使用应用程序的“服务器端”时区，该时区由应用程序 app 配置文件中的时区选项定义。

请参阅我们关于时区自定义的文档以获取更多信息。

`Date` / `DateTime` 字段和 HTML5

Nova 4 利用本机 <input type="date" /> 和 <input type="datetime-local" /> 元素来呈现 Date 和 DateTime 字段。因此，以下方法已从 Nova 4 中删除

firstDayOfWeek()
format()
pickerFormat()
pickerDisplayFormat()
incrementPickerHourBy()
incrementPickerMinuteBy()

Algolia 地点字段

不幸的是，Algolia 将于 2022 年 5 月 31 日停止其“地点”API；因此，Place 字段已被弃用，我们鼓励你迁移到 Text 字段以获取街道地址和城市。

中等影响更改

更新自定义工具、卡片、字段、过滤器

先决条件

为了轻松将自定义包升级到 Nova 4，请查看并复制以下文件，从 Laravel Nova 的 src/Console/tool-stubs 目录复制到您自己的自定义包

nova.mix.js
package.json
webpack.mix.js

由于 Nova 4 将我们的前端依赖项升级到 Inertia、Vue 3 和 Tailwind 2，因此有必要查看所有自定义工具并相应地对其进行升级。以下是可以找到必要的更改的一般概述；但是，如果您的自定义 Nova 包依赖于仅支持 Vue 2 或早期版本的 Tailwind 的第三方包，则可能需要进行其他更改。

Vue 3

此更改主要影响利用 Vue 路由的自定义工具的安装。

Nova 4 已更新为使用 Vue 3，为了升级所有自定义卡片、自定义字段、自定义过滤器、资源工具和工具以支持 Vue 3，请对应用程序的 webpack.mix.js 进行以下更改

// Before...
mix.js("resources/js/field.js", "js");

// After...
require("./nova.mix");
  
mix
  .setPublicPath('dist')
  .js('resources/js/tool.js', 'js')
  .vue({ version: 3 })
  .css('resources/css/tool.css', 'css')
  .nova('vendor/package')

使用 Inertia.js 替换 Vue 路由

此更改主要影响利用 Vue 路由的自定义工具的安装。

Nova 4 已用 Inertia.js 替换了 Vue 路由。因此，自定义工具应从注册 Vue 路由迁移到注册 Inertia.js 页面组件和后端路由。例如，给定以下 Nova 3 Vue 路由注册

// Within tool.js...

Nova.booting((Vue, router) => {
  router.addRoutes([
    {
      name: "sidebar-tool",
      path: "/sidebar-tool",
      component: require("./components/Tool"),
    },
  ]);
});

在使用 Nova 4 时，您应该像这样使用 Inertia 注册工具组件

// Within tool.js...

Nova.booting((Vue) => {
  Nova.inertia("SidebarTool", require("./component/Tool").default);
});

php

// Within ToolServiceProvider.php...

use Illuminate\Http\Request;
use Laravel\Nova\Nova;

Nova::router()
    ->group(function ($router) {
        $router->get('sidebar-tool', function (Request $request) {
            return inertia('SidebarTool');
        });
    });

删除 `laravel-nova` NPM 依赖项

此更改主要影响利用 Vue 路由的自定义工具的安装。

先决条件

为了轻松将自定义包升级以支持 Nova 4，请查看并复制以下文件，从 Laravel Nova 的 src/Console/stubs 中复制，特别是以下文件

nova.mix.js
packages.json
webpack.mix.js

Nova 的早期版本需要 laravel-nova NPM 包。在 4.0 中，不再需要此包，因为每个 mixin 已集成到 Nova 本身中。若要升级您创建的任何自定义包，您必须更新 webpack.mix.js 文件以定义指向 vendor/laravel/nova/resources/js/mixins/packages.js 的别名

通常，在 Laravel 应用程序的 nova-components 目录中开发的自定义 Nova 工具、资源工具、卡片和其他自定义包可以通过定义指向 Nova 安装中位于根应用程序的 vendor 目录中的文件的 laravel-nova 别名来引用 Nova 自身的 packages.js 文件。此别名通常在自定义包的 nova.mix.js 文件中定义

'laravel-nova': path.join(
  __dirname,
  '../../vendor/laravel/nova/resources/js/mixins/packages.js'
),

在 nova-components 目录之外开发的自定义 Nova 包应将 laravel/nova 声明为“dev”Composer 依赖项，然后定义指向自定义包的 vendor 目录中的 packages.js 文件的 laravel-nova Mix 别名

'laravel-nova': path.join(
  __dirname,
  'vendor/laravel/nova/resources/js/mixins/packages.js'
),

为了使用 laravel-nova mixin 编译自定义包资产，您需要通过运行以下命令来准备 laravel/nova 的 node_modules

bash

npm run nova:install

# Or use the explicit command...
npm --prefix='vendor/laravel/nova' ci

保存时取消事件

创建或更新资源时，Nova 3 忽略事件取消。例如，即使事件侦听器返回 false，以下代码仍会将 User 资源保留到数据库中

php

User::updating(function ($model) {
    return false;
});

但是，此代码将在 Nova 4 中引发 Laravel\Nova\Exceptions\ResourceSaveCancelledException 异常。

`Field::default` 方法仅适用于创建、附加和操作请求

Nova 4 将不再解析“index”和“detail”请求的默认值。如果您需要定义模型的默认属性值，请使用 Eloquent 的 $attributes 属性

php

use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    /**
     * The model's attributes.
     *
     * @var array
     */
    protected $attributes = [
        'timezone' => 'UTC',
    ];
}

关系名称约定

给定以下字段定义，Nova 3 将假设关系方法名为 purchased_books；然而，Nova 4 将正确地假设关系方法名为 purchasedBooks。

php

BelongsToMany::make('Purchased Books'),

`Action::actionClass` 方法已移除

Nova 4 不再允许通过操作的 actionClass 方法向操作确认模态按钮添加自定义 CSS 样式。

影响较小的更改

需要 Eloquent 用户提供程序

Nova 4 要求身份验证用户提供程序为 eloquent，以便解析有关当前经过身份验证用户的相关信息。

在应用程序的默认 config/auth.php 配置文件中，指定了 Eloquent 用户提供程序，并指示在检索用户时使用 App\Models\User 模型。你可以根据应用程序的需要在配置文件中更改这些值。

减少编码的筛选字符串长度

Nova 4 在筛选字符串 URL 中引入了较短的键值映射，这减少了 URL 的总长度。此更改不影响已添加书签的 URL；但是，与 Vuex 深度交互的第三方包工具开发人员可能希望确保他们的包在此更改后仍然有效。

`Action::showOnTableRow` 方法

Action::showOnTableRow 方法已被弃用。相反，我们建议更新你的代码以使用 showInline 方法

php

// Before...
(new ConsolidateTransaction)->showOnTableRow(),

// After...
(new ConsolidateTransaction)->showInline(),
(new ConsolidateTransaction)->onlyInline(),
(new ConsolidateTransaction)->exceptInline(),

授权优先级

Nova 4 对授权顺序/优先级进行了以下调整

授权用户是否可以 查看 资源不再依赖于 viewAny 权限。
无论 view 和 viewAny 权限如何，都可以执行操作。
破坏性操作现在将在回退到模型策略之前通过其自己的 canRun 方法进行授权。

有关 Nova 授权的更多详细信息可在资源策略文档和操作授权文档中找到。

更新已发布的存根

由于 Nova 4.0 中的各种更改，如果你之前发布了 Nova “存根”，则应重新发布它们。你可以通过使用 --force 选项执行 nova:stubs Artisan 命令来完成此操作

bash

php artisan nova:stubs --force

升级指南 ​

依赖项升级 ​

服务器 ​

客户端 ​

更新 Composer 依赖项 ​

更新配置、资产和翻译 ​

注册 Nova 许可证密钥和生产 URL ​

更新第三方 Nova 包 ​

高影响更改 ​

Nova 请求 ​

资源 ​

透镜 ​

操作 ​

筛选器 ​

主仪表盘类 ​

仪表盘方法 ​

客户端时区检测 ​

Date / DateTime 字段和 HTML5 ​

Algolia 地点字段 ​

中等影响更改 ​

更新自定义工具、卡片、字段、过滤器 ​

Vue 3 ​

使用 Inertia.js 替换 Vue 路由 ​

删除 laravel-nova NPM 依赖项 ​

保存时取消事件 ​

Field::default 方法仅适用于创建、附加和操作请求 ​

关系名称约定 ​

Action::actionClass 方法已移除 ​

影响较小的更改 ​

需要 Eloquent 用户提供程序 ​

减少编码的筛选字符串长度 ​

Action::showOnTableRow 方法 ​

授权优先级 ​

更新已发布的存根 ​

在此页面上

升级指南

依赖项升级

服务器

客户端

更新 Composer 依赖项

更新配置、资产和翻译

注册 Nova 许可证密钥和生产 URL

更新第三方 Nova 包

高影响更改

Nova 请求

资源

透镜

操作

筛选器

主仪表盘类

仪表盘方法

客户端时区检测

`Date` / `DateTime` 字段和 HTML5

Algolia 地点字段

中等影响更改

更新自定义工具、卡片、字段、过滤器

Vue 3

使用 Inertia.js 替换 Vue 路由

删除 `laravel-nova` NPM 依赖项

保存时取消事件

`Field::default` 方法仅适用于创建、附加和操作请求

关系名称约定

`Action::actionClass` 方法已移除

影响较小的更改

需要 Eloquent 用户提供程序

减少编码的筛选字符串长度

`Action::showOnTableRow` 方法

授权优先级

更新已发布的存根