README

这是一个 WordPress 依赖组件，允许您通过配置文件定义依赖项。您以这种方式定义的依赖项将自动注册和排队。

安装

使用此组件的最佳方式是通过 Composer

composer require brightnucleus/dependencies

基本用法

配置文件

要使用 DependencyManager，您首先需要创建一个配置文件（见 brightnucleus/config ），在其中定义您的依赖项。在传递给 DependencyManager 构造函数的配置根级别中，您将有一个用于每种类型依赖项的键，以及一个定义处理该特定类型依赖项的类的 handlers 键。以下是一个示例，展示了 DependencyManager 默认支持的设置

<?php

// Configure all your styles and scripts here.
$dependencies_config = [
	'styles'   => [ <individual style dependencies go here> ],
	'scripts'  => [ <individual script dependencies go here> ],
	'handlers' => [
		'scripts' => 'BrightNucleus\Dependency\ScriptHandler',
		'styles'  => 'BrightNucleus\Dependency\StyleHandler',
	],
];

// Pass the Config to the 'DependencyManager', with a vendor/package prefix.
return 'BrightNucleus' => [
	'Example' => [
		'DependencyManager' => $dependencies_config,
	],
];

您可以定义任意类型的依赖项，只要您还提供了实现该依赖项类型的 DependencyHandlerInterface 的相应类。

您为每个依赖项提供的参数取决于实现 DependencyHandlerInterface 的类的实现，有一个重要要求：每个依赖项都需要一个 handle 键来唯一标识它。

对于提供的两个依赖项处理程序，参数将通过传递到相应的 wp_register_* 和 wp_enqueue_* 函数，因此它们接受与这些函数相同的参数。

脚本

handle: (字符串) (必需) 脚本的唯一名称。
src: (字符串) (必需) 脚本资源的 URL。
deps: (数组) (可选) 该脚本所依赖的所有已注册脚本的句柄数组。

默认: array()
ver: (字符串) (可选) 指定脚本版本号的字符串。如果为 false，则使用 WordPress 版本。

默认: false
in_footer: (布尔值) (可选) 是否将脚本排队到 <body> 部分的底部部分。如果不是，则将其排队到 <head>。

默认: false

样式

handle: (字符串) (必需) 样式的唯一名称。
src: (字符串) (必需) 样式资源的 URL。
deps: (数组) (可选) 该样式所依赖的所有已注册样式的句柄数组。

默认: array()
ver: (字符串) (可选) 指定样式版本号的字符串。如果为 false，则使用 WordPress 版本。

默认: false
media: (字符串) (可选) 指定为该样式定义的媒体。

默认: 'all'

初始化

初始化 DependencyManager 并将其连接到 WordPress 是直接的。 DependencyManager 的构造函数需要一个 ConfigInterface 实现来完成其工作。在以下示例中，我们使用标准 Config 实现及其随 brightnucleus/config 包一起提供的 ConfigTrait 伴随。

然后，您可以将DependencyManager::register()方法挂钩到WordPress动作中，以便在正确的时间执行。

<?php
namespace BrightNucleus\Example;

use BrightNucleus\Config\ConfigInterface;
use BrightNucleus\Config\ConfigTrait;
use BrightNucleus\Dependency\DependencyManager;

class ExamplePlugin {

	use ConfigTrait;

	/**
	 * Instantiate a Plugin object.
	 *
	 * @param ConfigInterface $config Config to parametrize the object.
	 */
	public function __construct( ConfigInterface $config ) {
		$this->processConfig( $config );
	}

	/**
	 * Launch the initialization process.
	 */
	public function run() {
		add_action( 'plugins_loaded', [ $this, 'init_dependencies' ] );
	}

	/**
	 * Initialize DependencyManager and hook it up to WordPress.
	 */
	public function init_dependencies() {

		// Initialize dependencies.
		$dependencies = new DependencyManager(
			$this->config->getSubConfig( 'DependencyManager' )
		);
		// Register dependencies.
		add_action( 'init', [ $dependencies, 'register' ] );
	}
}

高级功能

条件注册

对于每个依赖项，您可以添加一个is_needed键，该键将被检查以决定是否加载依赖项。is_needed可以是任何评估为布尔值的表达式，或者是一个闭包（callable）。

如果is_needed包含一个闭包，该闭包将被执行，并接收一个名为$context的参数，该参数可以用来做出明智的决策。调用初始DependencyManager::register()的代码可以将任何有用的值传递到$context中，从而与这些is_needed闭包进行通信。

配置中is_needed键的示例

<?php
$dependencies_config = [
	'script' => [
		'handle' => 'test_script',
		'is_needed' => function ( $context ) {
			return array_key_exists( 'page_template', $context )
			&& 'test-template' === $context['page_template'];
		},
	],
];

本地化数据

如果您需要将PHP代码中的数据传递到JavaScript依赖项中，您可以通过在脚本配置中添加一个'localize'键来实现。

将动态PHP数据传递到JavaScript依赖项的示例

<?php
$dependencies_config = [
	'scripts' => [
		[
			'handle'    => 'bn-example-script-handle',
			'src'       => BN_EXAMPLE_PLUGIN_DIR . 'js/bn-example-script.js',
			'deps'      => [ 'jquery' ],
			'ver'       => '1.2.1',
			'in_footer' => true,
			'localize'  => [
				'name' => 'BNExampleData',
				'data' => function( $context ) {
					return [
						'ajaxurl' => admin_url( 'admin-ajax.php' ),
						'context' => $context,
					];
				},
			],
		],
	],
];

当您的bn-example-script.js文件执行时，它将能够访问一个全局的BNExampleData对象来检索其数据。例如，console.log( BNExampleData.ajaxurl );将打印当前网站的AJAX URL到控制台。

内联脚本

如果您需要向JavaScript依赖项添加内联脚本，您可以通过在脚本配置中添加一个'add_inline'键来实现。

向JavaScript依赖项添加内联脚本的示例

<?php
$dependencies_config = [
	'scripts' => [
		[
			'handle'     => 'bn-example-script-handle',
			'src'        => BN_EXAMPLE_PLUGIN_DIR . 'js/bn-example-script.js',
			'deps'       => [ 'jquery' ],
			'ver'        => '1.2.1',
			'in_footer'  => true,
			'add_inline' => 'window.initialite_my_script();',
		],
	],
];

当您的bn-example-script.js文件执行时，它将立即跟随您提供的内联脚本片段。

自定义上下文数据

可以通过DependencyManager使用$context参数传递自定义数据。这可以在您的is_needed闭包中用来控制注册和队列。

如果您直接调用DependencyManager::register()方法，只需将该调用中的$context参数添加即可。

<?php
/**
 * Register all dependencies.
 *
 * @param mixed $context Optional. The context to pass to the dependencies.
 */
public function register( $context = null );

但是，如果您想将register()方法挂钩到WordPress动作中，则需要间接地进行，如下面的示例所示

<?php
class ExamplePlugin {

	// <...>

	/** @var BrightNucleus\Dependency\DependencyManager $dependencies */
	protected $dependencies;

	/**
	 * Initialize DependencyManager and hook it up to WordPress.
	 */
	public function init_dependencies() {

		// Initialize dependencies.
		$this->dependencies = new DependencyManager( $this->config );
		// Register dependencies.
		add_action( 'init', [ $this, 'register_with_context' ], 20 );
	}

	/**
	 * Register dependencies and pass collected context into them.
	 */
	public function register_with_context() {
		$context['example_key'] = 'example_value';
		$this->dependencies->register( $context );
	}
}

手动排队

DependencyManager的默认行为是在注册依赖项后自动队列所有依赖项。在某些情况下，您可能想要覆盖此行为并自行处理队列。

要覆盖默认行为，需要将构造函数的第二个参数$enqueue设置为false。

然后，您可以使用DependencyManager::enqueue_handle()方法通过依赖项的handle来队列单个依赖项。

<?php
/**
 * Enqueue a single dependency retrieved by its handle.
 *
 * @param string $handle   The dependency handle to enqueue.
 * @param mixed  $context  Optional. The context to pass to the
 *                         dependencies.
 * @param bool   $fallback Whether to fall back to dependencies registered
 *                         outside of DependencyManager. Defaults to false.
 * @return bool Returns whether the handle was found or not.
 */
public function enqueue_handle( $handle, $context = null, $fallback = false );

与register()方法一样，您可以传递一个$context，该$context可以在is_needed闭包中进行检查。

如果您将第三个参数$fallback设置为true，则将搜索所有未在通过DependencyManager注册的依赖项集合中找到的任何$handle，这可以在DependencyManager外部注册的依赖项中查找。这是队列内置在WordPress安装中的依赖项的便捷方式。

贡献

欢迎所有反馈/错误报告/拉取请求。

许可证

此代码在MIT许可证下发布。

有关完整的版权和许可信息，请查看与源代码一起分发的LICENSE文件。LICENSE

brightnucleus / dependencies

维护者

详细信息