README

简介

WPAssets 是一个用于在 WordPress 中管理资产的 PHP 类。它集成了 Webpack 的 manifest.json 文件，以结构化和可扩展的方式自动排队 CSS、JS 以及处理 PHP 依赖（使用 Dependency Extraction Webpack 插件）。这简化了 WordPress 主题和插件中的资产管理。

特性

自动资产排队：轻松排队 Webpack 的 manifest.json 中定义的 JavaScript、CSS 和 PHP 文件。
基于包的资产管理：通过将资产打包成逻辑入口点来管理它们。
命名空间支持：为您的资产添加自定义命名空间前缀以实现更好的组织。
PHP 依赖支持：自动将 PHP 文件作为资产依赖项包含在内。

通过 Composer 安装

您可以通过 Composer 安装 WPAssets。在 WordPress、主题或插件目录中运行以下命令

composer require milbareu/wordpress-webpack-asset-manager

1. 在 WordPress 中排队资产

要排队一个包（包括 CSS、JS 以及可选的 PHP 文件），请使用 WPAssets::enqueueBundle() 函数。此函数从 Webpack 生成的 manifest.json 文件中拉取所需的资产。

// Example: Enqueue the 'main' bundle with the namespace 'mytheme'
WPAssets::enqueueBundle('main', 'mytheme');

// Example: Enqueue the 'editor' bundle with the default namespace
WPAssets::enqueueBundle('editor');

2. functions.php 中的示例设置

以下是使用 WPAssets 在 WordPress 主题中管理资产的一个示例

<?php

use MB\WPAssets\WPAssets;

// Register the theme assets
add_action('wp_enqueue_scripts', function () {
    WPAssets::enqueueBundle('main', 'mytheme');
}, 100);

// Register assets for the block editor
add_action('enqueue_block_editor_assets', function () {
    WPAssets::enqueueBundle('editor');
}, 100);

2.1 示例 Webpack 配置

example/ 文件夹包含您可以根据项目需求修改的示例 Webpack 配置文件。这些配置支持生产和开发环境，允许您为每种情况构建优化的资产。

2.2 基于环境的构建

确保您的 Webpack 配置支持基于环境的构建。例如，您可以定义针对开发和生产环境的不同配置。这些将生成针对每个用例优化的不同资产版本。

在您的 Webpack 配置文件中（请参阅 example/ 文件夹）

开发：生成源映射和未压缩的资产。
生产：压缩资产并删除不必要的注释。

3. Webpack Manifest 结构

您的 Webpack 配置应输出一个包含 entrypoints 对象的 manifest.json。以下是 manifest.json 的示例结构

{
  "entrypoints": {
    "main": {
      "assets": {
        "css": [
          "/styles/main.css"
        ],
        "js": [
          "/scripts/main.js"
        ],
        "php": [
          "/scripts/main.asset.php"
        ]
      }
    },
    "editor": {
      "assets": {
        "css": [
          "/styles/editor.css"
        ],
        "js": [
          "/scripts/editor.js"
        ],
        "php": [
          "/scripts/editor.asset.php"
        ]
      }
    }
  }
}

4. 函数参考

enqueueBundle(string $entry, string $namespace = 'wpa') 为指定的入口点排队 CSS、JS 和 PHP 文件。

$entry：入口点的名称（例如，'main'、'editor'）。
$namespace（可选）：资产处理的名称前缀（默认为 'wpa'）。

示例

WPAssets::enqueueBundle('main', 'mytheme');

getAsset(string $assetName, bool $getContents = false): ?string

根据其名称检索单个资产的位置或内容。

$assetName：资产的名称（例如，'main.css'、'main.js'）。
$getContents：是否返回文件的内容（true）或 URL（false）。

示例

$mainCssUrl = WPAssets::getAsset('main.css'); // Get URL of main.css

getAssetDependencies(string $entry): array

从给定入口的 .asset.php 文件中检索资产依赖项。

$entry：入口名称（例如，'main.js'）。

示例

$deps = WPAssets::getAssetDependencies('main.js');

5. 高级使用

要包含 Webpack 配置中的特定 PHP 文件，请确保它们在 manifest.json 中对应入口点的 php 键下列出。当排队包时，这些文件将自动使用 include_once 包含。

示例

"php": [
"/scripts/main.asset.php"
]

贡献

请随时通过提交问题或拉取请求来贡献。您的贡献有助于改进此项目并使其对社区更有用。

许可协议

本项目采用 MIT 许可协议。

免责声明

这个Webpack配置已经被调整以满足我的特定需求和偏好。虽然它能满足我的项目需求，但请注意，我不是Webpack专家，这个配置可能不适合所有项目或环境。

您可以自由使用、修改或根据自身需求进行适配，但请自行承担风险。我不能保证它在所有情况下都能完美工作，因此请确保在您的开发和生产环境中彻底测试。

milbareu / wordpress-webpack-asset-manager

维护者

详细信息