lcharette/webpack-encore-twig

Webpack Encore 独立 Twig 函数

1.2.0 2023-12-07 02:32 UTC

This package is auto-updated.

Last update: 2024-09-07 04:17:17 UTC


README

Version PHP Version License Build Codecov StyleCI PHPStan Donate

Webpack Encore 独立 Twig 函数。允许在不需要 Symfony 的情况下在 Twig 模板中使用 Webpack Encore。针对 PHP-DI 风格容器进行了优化。

这允许您通过读取 entrypoints.jsonmanifest.json 文件来使用 Webpack Encore 的 splitEntryChunks()enableVersioning() 功能。

安装

composer require lcharette/webpack-encore-twig

文档 & 使用

每次运行 Encore 时,您的输出文件夹(默认位置:public/build/)中都会生成两个配置文件:entrypoints.jsonmanifest.json。每个文件都很相似,都包含到最终、已版本化的文件名的映射。

第一个文件 – entrypoints.json – 在您的 webpack.config.js 中定义了 splitEntryChunks() 选项时生成,并由该包提供的 encore_entry_script_tags()encore_entry_link_tags() Twig 辅助函数读取。如果您使用这些函数,则您的 CSS 和 JavaScript 文件将使用新的、已版本化的文件名进行渲染。

第二个文件 - manifest.json - 在您的 webpack.config.js 中定义了 资产版本化 选项 (enableVersioning()) 时生成,并将用于获取 其他 文件的版本化文件名,例如字体文件或图像文件(尽管它还包含有关 CSS 和 JavaScript 文件的信息)。

这两个功能(splitEntryChunks()enableVersioning())分别定义了两个不同的 Twig 扩展(分别为 EntrypointsTwigExtensionVersionedAssetsTwigExtension),以防您需要/想要只启用这两个中的任何一个。

splitEntryChunksentrypoints.json

Encore 会写入一个包含每个“入口”所需的所有文件列表的 entrypoints.json 文件。要引用 Twig 中的条目,您需要将 EntrypointsTwigExtension 扩展添加到 Twig 环境。它接受 EntrypointLookup,它本身接受 entrypoints.json 的路径,以及 TagRenderer(它本身接受 EntrypointLookup)。

use Lcharette\WebpackEncoreTwig\EntrypointsTwigExtension;
use Lcharette\WebpackEncoreTwig\TagRenderer;
use Symfony\WebpackEncoreBundle\Asset\EntrypointLookup;
use Twig\Environment;
use Twig\Loader\FilesystemLoader;

$entryPoints = new EntrypointLookup('./path/to/entrypoints.json');
$tagRenderer = new TagRenderer($entryPoints);
$extension = new EntrypointsTwigExtension($entryPoints, $tagRenderer);

// Create Twig Environment and add extension
$loader = new FilesystemLoader('./path/to/templates');
$twig = new Environment($loader);
$twig->addExtension($extension);

现在,要渲染特定“入口”(例如 entry1)的所有 scriptlink 标签,您可以

{# any template or base layout where you need to include a JavaScript entry #}

{% block javascripts %}
    {{ parent() }}

    {{ encore_entry_script_tags('entry1') }}

    {# or render a custom attribute #}
    {#
    {{ encore_entry_script_tags('entry1', attributes={
        defer: true
    }) }}
    #}
{% endblock %}

{% block stylesheets %}
    {{ parent() }}

    {{ encore_entry_link_tags('entry1') }}
{% endblock %}

如果您需要更多控制,可以使用 encore_entry_js_files()encore_entry_css_files() 方法获取所需文件列表,然后手动循环创建 scriptlink 标签。

script 和 link 标签的自定义属性

可以通过三种不同的方式向渲染的 scriptlink 添加自定义属性

  1. 通过全局配置,使用 TagRenderer 构造函数中的 defaultAttributes 参数,或使用设置方法

    $tagRenderer->setDefaultAttributes(['crossorigin' => 'anonymous']);
    
  2. 通过 TagRenderer 构造函数中的特定 scriptlink 参数,或使用设置方法

    $tagRenderer->setDefaultScriptAttributes(['defer' => null]);
    $tagRenderer->setDefaultLinkAttributes(['hreflang' => 'en']);
    
  3. 在 Twig 中渲染时 - 请参阅上文中的 attributes 选项。

enableVersioningmanifest.json

要读取要链接(例如,通过 img 标签)到特定资产的清单文件,您需要将 VersionedAssetsTwigExtension 扩展添加到 Twig 环境。它接受 JsonManifest,它本身接受 manifest.json 的路径。

use Lcharette\WebpackEncoreTwig\JsonManifest;
use Lcharette\WebpackEncoreTwig\VersionedAssetsTwigExtension;
use Twig\Environment;
use Twig\Loader\FilesystemLoader;

$manifest = new JsonManifest('./path/to/manifest.json');
$extension = new VersionedAssetsTwigExtension($manifest);

// Create dumb Twig and test adding extension
$loader = new FilesystemLoader();
$twig = new Environment($loader);
$twig->addExtension($extension);

在你的Twig模板中,只需像通常一样将每个路径包裹在Twig的asset()函数中

<img src="{{ asset('build/images/logo.png') }}" alt="ACME logo">

依赖注入与自动装配

当使用带有自动装配的PSR依赖注入容器,如PHP-DI时,您可以通过相应的接口(EntrypointLookupInterfaceJsonManifestInterface)在您的定义工厂中定义EntrypointLookupJsonManifest。例如

use Lcharette\WebpackEncoreTwig\JsonManifest;
use Lcharette\WebpackEncoreTwig\JsonManifestInterface;
use Symfony\WebpackEncoreBundle\Asset\EntrypointLookup;
use Symfony\WebpackEncoreBundle\Asset\EntrypointLookupInterface;

// ...

return [
    EntrypointLookupInterface::class => function () {
        return new EntrypointLookup('./path/to/entrypoints.json');
    },
    JsonManifestInterface::class => function () {
        return new JsonManifest('./path/to/manifest.json');
    },
];

EntrypointsTwigExtensionVersionedAssetsTwigExtension可以通过容器注入到您的其他类中

use Lcharette\WebpackEncoreTwig\EntrypointsTwigExtension;
use Lcharette\WebpackEncoreTwig\VersionedAssetsTwigExtension;

// ...

$extension = $container->get(EntrypointsTwigExtension::class);
$twig->addExtension($extension);

$extension = $container->get(VersionedAssetsTwigExtension::class);
$twig->addExtension($extension);

不使用Twig使用

可以使用TagRenderer类的底层公共方法在纯PHP和不使用Twig的情况下生成脚本和链接标签

entrypoints.json获取脚本和链接标签

$entryPoints = new EntrypointLookup('./path/to/entrypoints.json');
$tagRenderer = new TagRenderer($entryPoints);

// Returns the tags as string
$scriptsString = $tagRenderer->renderWebpackScriptTags('entry1');
$linksString = $tagRenderer->renderWebpackLinkTags('entry1');

// Returns the list of files as an array of strings
$jsFiles = $tagRenderer->getJavaScriptFiles('entry1');
$cssFiles = $tagRenderer->getCssFiles('entry1');

对于版本化的资产,使用JsonManifest类的底层公共方法也是如此

manifest.json获取版本化信息

$manifest = new JsonManifest('./path/to/manifest.json');
$path = $manifest->applyVersion('build/images/logo.png');

另请参阅

参考文献