logo

升级指南 ​

更新依赖项 ​

Nova 的上游依赖关系已经升级。你将在下面找到我们的依赖升级的完整列表：

后端 ​

  • PHP 7.3+
  • Laravel Framework 8.0+
  • doctrine/dbal 从 ^2.9 更新到 ^2.13.3|^3.1.2
  • laravel/ui 从 ^2.0|^3.0 更新到 ^3.3
  • symfony/* 从 ^5.0 更新到 ^5.4|^6.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 Request ​

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

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

php
use App\Nova\Dashboards\Main;

/**
 * 获取Nova仪表板上应显示的额外仪表板.
 *
 * @return array
 */
protected function dashboards()
{
    return [
        new Main,
    ];
}

仪表板方法 ​

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

php
/**
 * 获取仪表板的可显示名称。
 *
 * @return string
 */
public function label()
{
    return 'Post Stats';
}

/**
 * 获取仪表板的 URI 主键。
 *
 * @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日废除 "Places" 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 进行以下更改：

js
// 以前...
mix.js("resources/js/field.js", "js");

// 之后...
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 路由注册：

js
// Within tool.js...

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

使用 Nova 4 时，你应该使用 Inertia 注册工具组件，如下所示

js
// Within tool.js...

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

注册 Vue 组件后，应该为工具定义一个服务器端路由定义，以便对其进行渲染:

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 工具、资源工具、卡和其他自定义包可以通过定义 laravel-nova 别名来引用 Nova 自己的 packages.js 文件，该别名指向 Nova 安装中位于根应用程序 vendor 目录中的文件。此别名通常在自定义包的 nova.mix.js 文件中定义：

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

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

js
'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
// 以前...
(new ConsolidateTransaction)->showOnTableRow(),

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

授权优先级 ​

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

  • 用户是否可以 view 资源的授权不再取决于 viewAny 权限。
  • 无论 view 和 viewAny 权限如何，都可以执行动作。
  • 破坏性操作现在将通过其自己的 canRun 方法进行授权，然后再回到模型的策略。

有关 Nova 授权的更多详细信息，请访问 资源策略 和 动作授权.

更新已发布的桩件 ​

由于 Nova 4.0 中的各种变化，如果您以前发布过 Nova 桩件 "stubs"，则应重新发布它们。你可以通过执行带有 --force 选项的 nova:stubs Artisan 命令来实现这一点：

bash
php artisan nova:stubs --force