lcharette / webpack-encore-twig
Webpack Encore 独立 Twig 函数
Requires
- php: ^8.0
- symfony/webpack-encore-bundle: ^1.13|^2.1
- twig/twig: ^3.3
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.0
- phpstan/phpstan: ^1.1
- phpstan/phpstan-deprecation-rules: ^1.0
- phpstan/phpstan-mockery: ^1.0
- phpstan/phpstan-phpunit: ^1.0
- phpstan/phpstan-strict-rules: ^1.0
- phpunit/phpunit: ^9.5
- slam/phpstan-extensions: ^6.0
README
Webpack Encore 独立 Twig 函数。允许在不需要 Symfony 的情况下在 Twig 模板中使用 Webpack Encore。针对 PHP-DI 风格容器进行了优化。
这允许您通过读取 entrypoints.json
和 manifest.json
文件来使用 Webpack Encore 的 splitEntryChunks()
和 enableVersioning()
功能。
安装
composer require lcharette/webpack-encore-twig
文档 & 使用
每次运行 Encore 时,您的输出文件夹(默认位置:public/build/
)中都会生成两个配置文件:entrypoints.json
和 manifest.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 扩展(分别为 EntrypointsTwigExtension
和 VersionedAssetsTwigExtension
),以防您需要/想要只启用这两个中的任何一个。
splitEntryChunks
和 entrypoints.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
)的所有 script
和 link
标签,您可以
{# 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()
方法获取所需文件列表,然后手动循环创建 script
和 link
标签。
script 和 link 标签的自定义属性
可以通过三种不同的方式向渲染的 script
或 link
添加自定义属性
-
通过全局配置,使用 TagRenderer 构造函数中的
defaultAttributes
参数,或使用设置方法$tagRenderer->setDefaultAttributes(['crossorigin' => 'anonymous']);
-
通过 TagRenderer 构造函数中的特定 script 或 link 参数,或使用设置方法
$tagRenderer->setDefaultScriptAttributes(['defer' => null]); $tagRenderer->setDefaultLinkAttributes(['hreflang' => 'en']);
-
在 Twig 中渲染时 - 请参阅上文中的
attributes
选项。
enableVersioning
和 manifest.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时,您可以通过相应的接口(EntrypointLookupInterface
和JsonManifestInterface
)在您的定义工厂中定义EntrypointLookup
和JsonManifest
。例如
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'); }, ];
EntrypointsTwigExtension
和VersionedAssetsTwigExtension
可以通过容器注入到您的其他类中
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');