README

此插件为 CakePHP 提供了一个辅助类，以方便使用 Vite JS。

当运行 Vite 开发服务器时，辅助类提供正确的脚本标签以实现热模块替换和页面重新加载。

在生产模式下，辅助类加载捆绑的文件。支持 @vitejs/plugin-legacy，将为不支持 JavaScript 模块的旧浏览器（例如旧版 iOS 设备）插入 nomodule-标签。

本说明针对版本 1.x。如果您是从 0.x 迁移过来的并且某些内容不清楚，请阅读 /docs 下的迁移指南。如果您遇到问题，请随时提交问题。

安装

您可以使用 composer 将此插件安装到您的 CakePHP 应用程序中。

CakePHP 版本映射

安装此插件推荐的方式是

composer require passchn/cakephp-vite

在 Application.php 中加载插件

bin/cake plugin load ViteHelper

在 AppView.php 中加载辅助类

$this->loadHelper('ViteHelper.ViteScripts');

用法

在您的 php-layout 中，在 html head 中包含以下内容

<?= $this->fetch('css') ?>

在 </body> 标签关闭之前插入此行

<?= $this->fetch('script') ?>

这些是 CakePHP 中的默认视图块。在书中了解更多关于视图块的信息。

在您的 php-template 或布局中，您可以使用以下方式导入 JavaScript 文件

<?php $this->ViteScripts->script($options) ?>

… 或者使用此快捷方式导入单个入口点

<?php $this->ViteScripts->script('webroot_src/main.ts') ?>

如果您在 JavaScript 文件中导入了 CSS 文件，此方法会自动将您的 CSS 标签附加到 CSS 视图块。

如果您在 vite-config 中没有定义任何 CSS-条目，您可以跳过 ::css() 方法调用。

在您的 php-template 中，您可以使用以下方式导入 CSS 文件

<?php $this->ViteScripts->css($options) ?>

… 或者使用此快捷方式导入单个入口点

<?php $this->ViteScripts->css('webroot_src/style.css') ?>

配置

此插件包含一些默认配置。您可能需要根据您的配置进行更改。或者您可能根本不需要任何配置。

您可以通过辅助方法的 $options 来覆盖一些配置设置，或者您可以将自己的 ViteHelperConfig 实例作为第二个参数传递给辅助方法。

'ViteHelper' => [
    'build' => [
        'outDirectory' => false, // output directory of build assets. string (e.g. 'dist') or false.
        'manifest' => WWW_ROOT . 'manifest.json', // absolute path to manifest
    ],
    'development' => [
        'scriptEntries' => ['someFolder/myScriptEntry.ts'], // relative to project root
        'styleEntries' =>  ['someFolder/myStyleEntry.scss'], // relative to project root. Unnecessary when using css-in-js.
        'hostNeedles' => ['.test', '.local'], // to check if the app is running locally
        'url' => 'https://:3000', // url of the vite dev server
    ],
    'forceProductionMode' => false, // or true to always serve build assets
    'plugin' => false, // or string 'MyPlugin' to serve plugin build assets
    'productionHint' => 'vprod', // can be a true-ish cookie or url-param to serve build assets without changing the forceProductionMode config
    'viewBlocks' => [
        'css' => 'css', // name of the css view block
        'script' => 'script', // name of the script view block
    ],
],

您可以在 app.php、app_local.php 或 app_vite.php 中覆盖默认值。

有关参考，请参阅插件的 app_vite.php。

示例

return [
    'ViteHelper' => [
        'forceProductionMode' => 1,
        'development' => [
            'hostNeedles' => ['.dev'], // if you don't use one of the defaults
            'url' => 'https://192.168.0.88:3000',
        ],
    ],
];

带有选项的辅助方法使用

您可以将一个 $options 数组传递给覆盖配置或完全跳过需要 ViteHelper 配置的必要性。

选项对于 ::script() 和 ::css() 大多数是相同的。

示例

$this->ViteScripts->script([

    // this would append both the scripts and the css to a block named 'myCustomBlock'
    // don't forget to use the block through $this->fetch('myCustomBlock')
    'block' => 'myCustomBlock',
    'cssBlock' => 'myCustomBlock', // for ::script() only – if you use css imports inside js.

    // files that are entry files during development and that should be served during production
    'files' => [
        'webroot_src/main.ts',
    ],

    // "devEntries" is like "files". If you set "files", it will override both "devEntries" and "prodFilters"
    'devEntries' => ['webroot_src/main.ts']

    // "prodFilter" filters the entry files. Useful for code-splitting if you don't use dynamic imports
    'prodFilter' => 'webroot_src/main.ts' // as string if there's only one option
    'prodFilter' => 'main.ts' // also works - only looks for parts of the string
    'prodFilter' => ['main.ts'] // as array - same as above with multiple files
    'prodFilter' => function (ManifestRecord $record) { /* do something with the record and return true or false */ }
]);

注意：在运行开发服务器时，您需要设置 devEntries。它们必须在配置中设置或在辅助方法中设置。相比之下，如果您对 PHP 侧代码拆分感兴趣并且不使用 JavaScript 中的动态导入，则只需设置 files 或 prodFilter。

如何定义入口取决于您的项目和用例。如果您不使用 prodFilter 或 files，则插件将为您服务所有入口文件，这可能正是您想要的情况。所以不要过度配置它 ;)

退出全局配置 + 插件开发

您可以通过 $config 参数使用多个配置来使用辅助方法。

2.3 版本新增：您可以将配置密钥而不是配置实例传递给辅助方法。默认配置密钥是 ViteHelper。

这可能在使用插件脚本或开发插件时很有用。

<?php $this->ViteScripts->pluginScript('MyPlugin', devMode: true, config: 'MyPlugin.ViteConfig'); ?>

上面的示例使用便捷方法来加载MyPlugin的插件脚本。DevMode已被启用，助手将使用键为MyPlugin.ViteConfig的CakePHP配置。这样，您可以限制您的应用程序和插件配置的作用域。

假设manifest.json直接位于您的插件的webroot中。如果不是这样，您应该通过build.manifest配置选项定义绝对路径。

Vite JS打包器/开发服务器

例如，通过yarn安装Vite

yarn create vite

建议添加遗留插件

yarn add -D @vitejs/plugin-legacy

有关更多信息，请参阅vitejs.dev上的Scaffolding Your First Vite Project。

配置

安装后，您可能需要稍微重构一下文件，以便在PHP项目中理解其含义。该插件的默认配置假设您将您的js、ts、scss等文件放在/webroot_src。

构建文件默认将放在/webroot/assets。您的vite配置文件（vite.config.js或*.ts）保持在项目根目录。

需要：vite/plugin配置和目录结构的示例。欢迎通过PR贡献，展示您的项目如何使用此插件。

贡献

您可以通过pull requests为此插件做出贡献。如果您遇到错误，您可以打开一个问题。

passchn / cakephp-vite

维护者

详细信息

README

安装

CakePHP 版本映射

用法

配置

带有选项的辅助方法使用

示例

退出全局配置 + 插件开发

Vite JS打包器/开发服务器

配置

推荐配置

贡献